Using Plugins in Gatsby

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:

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.

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:

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.

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:

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! ⏳👈