title: 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"](/docs/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](/docs/node-apis/), [Browser](/docs/browser-apis/), and [SSR APIs](/docs/ssr-apis/). Consider the following `gatsby-config` with a plugin called `gatsby-plugin-console-log`:

module.exports = {

plugins: [

{

resolve: `gatsby-plugin-console-log`,

options: { optionA: true, optionB: false, message: "Hello world" },

},

],

}

With the `optionA`, `optionB`, and `message` options passed into the plugin, the code for `gatsby-plugin-console-log` is able to access the values `true`, `false`, and `Hello world` by their keys.

For example, `gatsby-plugin-console-log` can access the `message` in order to log its value to the console inside of the `onPreInit` API:

exports.onPreInit = (_, pluginOptions) => {

console.log(

`logging: "${pluginOptions.message || `default message`}" to the console` // highlight-line

)

}

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.

_Like arguments in any JavaScript function, you can use a different (more specific) name like `themeOptions` if you are building a plugin that will be used as a theme._

Any JavaScript data type can be passed in as an option.

The following table lists possible options values and an example plugin that makes use of them.

| Data Type | Sample Value | Example Plugin |

| --------- | -------------------------------- | ----------------------------------------------------------------- |

| Boolean | `true` | [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) |

| String | `/src/data/` | [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) |

| Array | `["/about-us/", "/projects/*"]` | [`gatsby-plugin-offline`](/packages/gatsby-plugin-offline/) |

| Object | `{ default: "./src/layout.js" }` | [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/) |

**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`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality.

- [Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options)

This is an example repository demonstrating how to add options to a plugin you've authored.

In this directory, be sure to install dependencies for Gatsby:

npm install

Then run `gatsby develop`:

gatsby develop

In your command line output, you should then see the text listed below. This text is showing how the code for each plugin is run sequentially thanks to the Node API implemented.

$ gatsby develop

success open and validate gatsby-configs - 0.034s

success load plugins - 0.050s

logging: "Hello world" to the console

logging: "default message" to the console

success onPreInit - 0.022s

If you refer to the `gatsby-config` in this example site, you'll see two plugins included in the plugins array. In actuality, it is the same plugin, `gatsby-plugin-console-log`, configured in two different ways. The plugin logs a message to the console when you run `gatsby develop`.

In the first instance, `gatsby-plugin-console-log` is configured with options passed in and will display the custom message.

The second configuration does not include options, so the plugin will log a default message. You can read about adding local plugins [in the Gatsby docs](https://www.gatsbyjs.org/docs/loading-plugins-from-your-local-plugins-folder/).

module.exports = {

siteMetadata: {

title: `Using plugin options`,

description: `An example Gatsby site using options with a local plugin`,

author: `@gatsbyjs`,

},

plugins: [

// including a plugin from the plugins folder with options

{

resolve: `gatsby-plugin-console-log`,

options: { message: "Hello world" },

},

// including the same plugin without any options, the plugin will use a default message

`gatsby-plugin-console-log`,

],

{

"name": "using-plugin-optons",

"description": "An example with the default starter using a plugin with options",

"version": "0.1.0",

"dependencies": {

"gatsby": "^2.18.12",

"prop-types": "^15.7.2",

"react": "^16.12.0",

"react-dom": "^16.12.0",

"react-helmet": "^5.2.1"

},

"devDependencies": {

"prettier": "^1.19.1"

},

"keywords": [

"gatsby"

],

"license": "MIT",

"scripts": {

"build": "gatsby build",

"develop": "gatsby develop",

"format": "prettier --write \"**/*.{js,jsx,json,md}\"",

"start": "npm run develop",

"serve": "gatsby serve",

"clean": "gatsby clean",

"test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1"

}

}

exports.onPreInit = (_, pluginOptions) => {

// uses the plugin options from the gatsby-config and uses it, or a default value

console.log(

`logging: "${pluginOptions.message || `default message`}" to the console`

)

{

"name": "gatsby-plugin-console-log",

"version": "1.0.0",

"description": "Log stuff in a Gatsby site's build process",

"main": "index.js",

"license": "MIT"

}

import { Link } from "gatsby"

import PropTypes from "prop-types"

import React from "react"

const Header = ({ siteTitle }) => (

<header

style={{

background: `rebeccapurple`,

marginBottom: `1.45rem`,

}}

>

<div

style={{

margin: `0 auto`,

maxWidth: 960,

padding: `1.45rem 1.0875rem`,

}}

>

<h1 style={{ margin: 0 }}>

<Link

to="/"

style={{

color: `white`,

textDecoration: `none`,

}}

>

{siteTitle}

</Link>

</h1>

</div>

</header>

Header.propTypes = {

siteTitle: PropTypes.string,

Header.defaultProps = {

siteTitle: ``,

export default Header

html {

font-family: sans-serif;

-ms-text-size-adjust: 100%;

-webkit-text-size-adjust: 100%;

}

body {

margin: 0;

-webkit-font-smoothing: antialiased;

-moz-osx-font-smoothing: grayscale;

}

h1 {

font-size: 2em;

margin: 0.67em 0;

}

html {

font: 112.5%/1.45em georgia, serif;

box-sizing: border-box;

overflow-y: scroll;

}

* {

box-sizing: inherit;

}

*:before {

box-sizing: inherit;

}

*:after {

box-sizing: inherit;

}

body {

color: hsla(0, 0%, 0%, 0.8);

font-family: georgia, serif;

font-weight: normal;

word-wrap: break-word;

font-kerning: normal;

-moz-font-feature-settings: "kern", "liga", "clig", "calt";

-ms-font-feature-settings: "kern", "liga", "clig", "calt";

-webkit-font-feature-settings: "kern", "liga", "clig", "calt";

font-feature-settings: "kern", "liga", "clig", "calt";

}

h1 {

margin-left: 0;

margin-right: 0;

margin-top: 0;

padding-bottom: 0;

padding-left: 0;

padding-right: 0;

padding-top: 0;

margin-bottom: 1.45rem;

color: inherit;

font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,

Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;

font-weight: bold;

text-rendering: optimizeLegibility;

font-size: 2.25rem;

line-height: 1.1;

}

h2 {

margin-left: 0;

margin-right: 0;

margin-top: 0;

padding-bottom: 0;

padding-left: 0;

padding-right: 0;

padding-top: 0;

margin-bottom: 1.45rem;

color: inherit;

font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,

Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;

font-weight: bold;

text-rendering: optimizeLegibility;

font-size: 1.62671rem;

line-height: 1.1;

}

p {

margin-left: 0;

margin-right: 0;

margin-top: 0;

padding-bottom: 0;

padding-left: 0;

padding-right: 0;

padding-top: 0;

margin-bottom: 1.45rem;

}

import React from "react"

import PropTypes from "prop-types"

import { useStaticQuery, graphql } from "gatsby"

import Header from "./header"

import "./layout.css"

const Layout = ({ children }) => {

const data = useStaticQuery(graphql`

return (

<>

<Header siteTitle={data.site.siteMetadata.title} />

<div

style={{

margin: `0 auto`,

maxWidth: 960,

padding: `0 1.0875rem 1.45rem`,

}}

>

<main>{children}</main>

<footer>

© {new Date().getFullYear()}, Built with

{` `}

<a href="https://www.gatsbyjs.org">Gatsby</a>

</footer>

</div>

</>

)

Layout.propTypes = {

children: PropTypes.node.isRequired,

export default Layout

import React from "react"

import Layout from "../components/layout"

const NotFoundPage = () => (

<Layout>

<h1>NOT FOUND</h1>

<p>You just hit a route that doesn&#39;t exist... the sadness.</p>

</Layout>

export default NotFoundPage

import React from "react"

import Layout from "../components/layout"

const IndexPage = () => (

<Layout>

<h1>Hi people</h1>

<p>

This site is to demonstrate using plugin options, you should see output in

the terminal showing a message you passed in to the plugin options, or a

default Hello world message!

</p>

</Layout>

export default IndexPage

- title: Configuring Usage with Plugin Options

link: /docs/configuring-usage-with-plugin-options/