Ecosystem

Design

Plugin Authoring

One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to extend and modify just about everything Gatsby does.

gatsby-transformer-* — a transformer plugin converts data from one format (e.g. CSV, YAML) to a JavaScript object. Use this naming convention if your plugin will be transforming data from one format to another.

gatsby-[plugin-name]-* — if a plugin is a plugin for another plugin 😅, it should be prefixed with the name of the plugin it extends (e.g. if it adds emoji to the output of gatsby-transformer-remark, call it gatsby-remark-add-emoji). Use this naming convention whenever your plugin will be included as a plugin in the options object of another plugin.

Local plugins

If a plugin is only relevant to your specific use-case, or if you’re developing a plugin and want a simpler workflow, a locally defined plugin is a convenient way to create and manage your plugin code.

Place the code in the plugins folder in the root of your project like this:

plugins
└── my-own-plugin
└── package.json

NOTE: You still need to add the plugin to your gatsby-config.js. There is no auto-detection of local plugins.

Like all gatsby-* files, the code is not processed by Babel. If you want
to use JavaScript syntax which isn’t supported by your version of Node.js, you
can place the files in a src subfolder and build them to the plugin folder
root.

What don’t you need plugins for?

Most third-party functionality you want to add to your website will follow standard Javascript and React.js patterns for importing packages and composing UIs. These do not require a Gatsby plugin!

Some examples:

Importing Javascript packages that provide general functionality, such as lodash or axios

Using React components or component libraries you want to include in your UI, such as Ant Design, Material UI, or the typeahead from your component library.