Tutorial

Using Plugins in Gatsby

Published on August 28, 2019
Default avatar

By Daniel Stout

Using Plugins in Gatsby

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

One of the biggest features of Gatsby.js is their incredible official plugin library. This large collection of Node.js packages taps directly into the Gatsby API, and provides easy ways to extend/add custom functionality to Gatsby websites without adding much extra code. In this short article, we’ll cover the basics of finding and implementing these plugins.

Finding Gatsby Plugins

When starting a Gatsby project, it’s always a great idea to look for available plugins that can make your job easier! Fortunately, the Gatsby website provides a huge searchable library that’s packed full of official plugins we can use.

Go ahead and open that link in a new tab, and scroll down through some of the available plugins. They’re sorted by popularity, so you will get a good idea of what other folks are regularly using. You can also make use of the search bar, of course! 🔍👀

Installing Gatsby Plugins

Specific plugin installation instructions can be found within each plugin’s page in the Gatsby plugin library, and you should always start there for best results. But in general, installing plugins in Gatsby is an easy two-step process!

1. Install plugin file(s)

Since these official Gatsby plugins are all Node.js packages, we can just install them by using npm install or yarn add. For example, we could install the gatsby-source-filesystem plugin like this:

$ yarn add gatsby-source-filesystem

Some plugins also require additional peer dependencies, and this will be mentioned on the plugin’s library page. A great example of this can be found in the Using Styled Components in Gatsby article, where we install the Gatsby plugin gatsby-styled-components and its two accompanying peer dependencies:

$ yarn add gatsby-plugin-styled-components
$ yarn add styled-components babel-plugin-styled-components

2. Configure for use

At this point, the plugin files have been added to our site — but we still need to configure them in Gatsby to make them function!

To make that happen, we just need to edit the gatsby-config.js file in our website’s root directory. All plugin configurations are placed inside the plugins array in this file:

gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-name`,
      options: {
        // plugin options, if any
      },
    },
    //...other plugins
  ]
}

The general format is like the above code, but the specific configuration depends on the plugin being used.

It’s important to always check the plugin’s page in the Gatsby plugin library for the most up-to-date instructions and configuration options.

This example code from the Gatsby documentation on using plugins is a wonderful example of the various ways that plugins can be configured in gatsby-config.js:

gatsby-config.js
module.exports = {
  plugins: [
    // Shortcut for adding plugins without options.
    "gatsby-plugin-react-helmet",
    {
      // Standard plugin with options example
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/src/data/`,
        name: "data",
      },
    },
    {
      resolve: "gatsby-plugin-offline",
      // Blank options, equivalent to string-only plugin
      options: {
        plugins: [],
      },
    },
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        // plugins inside plugins
        plugins: [`gatsby-remark-smartypants`],
      },
    },
  ],
}

Notice the shorthand form used for gatsby-plugin-react-helmet, as there’s no configuration options being used. Not only is there less code, but it’s also a bit easier to read!

Restart the dev server!

Now that we have installed and configured the plugins in gatsby-config.js, be sure to restart the dev server and test things out to make sure things are working properly.

It’s critical to restart the dev server anytime you edit the gatsby-config.js file, or things will not work as expected.

Local Plugins

It’s also possible to load plugins locally, which makes it possible to load privately-built and/or non-official plugins!

The easiest way is to create a new directory in the root of your site named plugins, and then place the local plugin files within it. After that, configuring the plugin in gatsby-config.js is exactly the same as a non-local plugin.

If for some special reason your local plugin needs to be in a different directory, you can simply use require.resolve to point Gatsby to it, like this:

gatsby-config.js
module.exports = {
  plugins: [
    "gatsby-plugin-sitemap",
    {
      resolve: require.resolve(`/path/to/local-plugin`),
    },
  ],
}

Creating Your Own Plugins

As hinted at above, it’s also possible to build your own plugins! While that information is beyond the scope of this introductory article, the Gatsby documentation on creating plugins contains some amazing material if you’re interested in learning more! 🧠

Final Thoughts

Gatsby is an amazing tool for building websites, and its huge library of official plugins is a big part of what makes it that way. Hopefully this short guide was helpful, but of course more info can be found in the official Gatsby plugins documentation.

I definitely recommend getting familiar with several of the popular plugins — as they can (and will) undoubtedly save you many hours of time! ⏳👈

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors
Default avatar
Daniel Stout

author

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
Leave a comment


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel