Configuring Plugin Usage with Plugin Options
Plugins loaded into a Gatsby site can have options passed in to customize how a plugin operates.
This guide refers to creating plugins, if you are looking for general information on using options with plugins refer to “Using a Plugin in Your Site”. If you are looking for options of a specific plugin, refer to its README.
A Gatsby plugin with options included makes those options available in the second argument of Gatsby Node, Browser, and SSR APIs. Consider the following
gatsby-config with a plugin called
message options passed into the plugin, the code for
gatsby-plugin-console-log is able to access the values
Hello world by their keys.
gatsby-plugin-console-log can access the
message in order to log its value to the console inside of the
The code above is called when
gatsby develop or
gatsby build is run. It takes the
message from the
options object in the config and logs it from
pluginOptions.message when the
onPreInit method is called.
The second argument passed into the function is where the options are held.
themeOptions if you are building a plugin that will be used as a theme.
The following table lists possible options values and an example plugin that makes use of them.
|Data Type||Sample Value||Example Plugin|
Note: Themes (which are a type of plugin) are able to receive options from a site’s
gatsby-config to be used in its
gatsby-config in order to allow themes to be composed together. This is done by exporting the
gatsby-config as a function instead of an object. You can see an example of this in the
gatsby-theme-blog-core repositories. Plugins are not capable of this functionality.