Recipes: Working with Plugins

A Gatsby plugin abstracts Gatsby APIs into an installable package. This means that modular chunks of Gatsby functionality aren’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can add external data, transform data, add third-party services (e.g. Google Analytics, Stripe), and more.

Using a plugin

Found a plugin you’d like to use in your project? Awesome! You can configure it for use by following the steps below. This recipe uses the gatsby-source-filesystem plugin as an example.

If you’d like to take a look at available plugins, check out the plugin library.

Video hosted on egghead.io.

Prerequisites

• An existing Gatsby site with a gatsby-config.js file

Directions

1. Install the gatsby-source-filesystem plugin by running the following command:

2. Add the plugin to your gatsby-config.js, and set any options it needs, the filesystem source plugin takes a name and path as options:

The instructions found in the README of the plugin you’re using can help you determine specifics about what configurations (if any) it requires. For this example to have an effect in your own site, you would need to create the src/images folder and place files inside of it.

3. Run gatsby develop, your plugin should run as your site builds.

Additional resources

• Learn more about configuring options or using default options in the Using a Plugin in Your Site guide.
• See an example Gatsby site using this configuration in the repo for the default Gatsby starter.

Creating a new plugin using a plugin starter

If you want to create your own plugin you can get started with the Gatsby plugin starter.

Video hosted on egghead.io.

Prerequisites

• An existing Gatsby site with a gatsby-config.js file

Directions

1. Outside of your Gatsby site, generate a new plugin based on the starter using the gatsby new command:

The directory structure should look something like this:

2. Add the plugin to your site’s gatsby-config.js, linking it to your local plugin’s root folder with require.resolve. The path (or name of the plugin) should be to the directory name you used when generating the plugin:

3. Run gatsby develop. To verify the plugin starter loaded correctly in your site it will log a message to the console saying it “Loaded” before the onPreInit step finishes:

4. Now you can implement browser, server-side rendering, or node APIs and your site will run them each time it loads your plugin!

Additional resources

• Read about creating and loading your own plugins in development in the Creating a Local Plugin guide