Gatsby Node APIs

Gatsby gives plugins and site builders many APIs for controlling your site.

Async plugins

If your plugin performs async operations (disk I/O, database access, calling remote APIs, etc.) you must either return a promise or use the callback passed to the 3rd argument. Gatsby needs to know when plugins are finished as some APIs, to work correctly, require previous APIs to be complete first.

// Promise API
exports.createPages = () => {
  return new Promise((resolve, reject) => {
    // do async work
  })
}

// Callback API
exports.createPages = (_, pluginOptions, cb) => {
  // do Async work
  cb()
}

If your plugin doesn't do async work, you can just return directly.

APIs



Reference

createLayouts

Tell plugins to add layouts. This extension point is called only after the initial sourcing and transformation of nodes plus creation of the GraphQL schema are complete so you can query your data in order to create layouts.

See also the documentation for createLayout.

Example

exports.createLayouts = ({ graphql, boundActionCreators }) => {
 boundActionCreators.createLayout({
   component: path.resolve(`src/templates/custom-layout.js`),
   id: 'custom', // optional - if not provided the filename will be used as id
  })
 }

createPages

Tell plugins to add pages. This extension point is called only after the initial sourcing and transformation of nodes plus creation of the GraphQL schema are complete so you can query your data in order to create pages.

See also the documentation for the boundActionCreator createPage.

Example

exports.createPages = ({ graphql, boundActionCreators }) => {
  const { createPage } = boundActionCreators
  return new Promise((resolve, reject) => {
    const blogPostTemplate = path.resolve(`src/templates/blog-post.js`)
    // Query for markdown nodes to use in creating pages.
    resolve(
      graphql(
        `
      {
        allMarkdownRemark(limit: 1000) {
          edges {
            node {
              fields {
                slug
              }
            }
          }
        }
      }
    `
      ).then(result => {
        if (result.errors) {
          reject(result.errors)
        }

        // Create blog post pages.
        result.data.allMarkdownRemark.edges.forEach(edge => {
            createPage({
              path: `${edge.node.fields.slug}`, // required
              component: slash(blogPostTemplate),
              context: {
                slug: edge.node.fields.slug,
              },
            })
        })

        return
      })
    )
  })
}

createPagesStatefully

Like createPages but for plugins who want to manage creating and removing pages themselves in response to changes in data not managed by Gatsby. Plugins implementing createPages will get called regularly to recompute page information as Gatsby’s data changes but those implementing createPagesStatefully will not.

An example of a plugin that uses this extension point is the internal plugin component-page-creator which monitors the src/pages directory for the adding and removal of JS pages. As its source of truth, files in the pages directory, is not known by Gatsby, it needs to keep its own state about its world to know when to add and remove pages.


generateSideEffects

Tell plugins with expensive “side effects” from queries to start running those now. This is a soon-to-be-replaced API only currently in use by gatsby-plugin-sharp.


modifyBabelrc

Let plugins extend/mutate the site’s Babel configuration. This API will change before 2.0 as it needs still to be converted to use Redux actions.


modifyWebpackConfig

Let plugins extend/mutate the site’s webpack configuration.

Refer to the Add custom webpack config docs page for detailed documentation on modifying webpack docs).


onCreateLayout

Called when a new layout is created. This extension API is useful for programmatically manipulating layouts created by other plugins


onCreateNode

Called when a new node is created. Plugins wishing to extend or transform nodes created by other plugins should implement this API.

See also the documentation for createNode and createNodeField

Example

exports.onCreateNode = ({ node, boundActionCreators }) => {
  const { createNode, createNodeField } = boundActionCreators
  // Transform the new node here and create a new node or
  // create a new node field.
}

onCreatePage

Called when a new page is created. This extension API is useful for programmatically manipulating pages created by other plugins e.g. if you want paths without trailing slashes.

See the guide Creating and Modifying Pages for more on this API.


onPostBootstrap

Called at the end of the bootstrap process after all other extension APIs have been called.


onPostBuild

The last extension point called after all other parts of the build process are complete.


onPreBootstrap

Called at the start of the bootstrap process before any other extension APIs are called.


onPreBuild

The first extension point called during the build process. Called after the bootstrap has completed but before the build steps start.


onPreExtractQueries

Run before GraphQL queries/fragments are extracted from JavaScript files. Useful for plugins to add more JavaScript files with queries/fragments e.g. from node_modules.

See gatsby-transformer-remark and gatsby-source-contentful for examples.


preprocessSource

Ask compile-to-js plugins to process source to JavaScript so the query runner can extract out GraphQL queries for running.


resolvableExtensions

Let’s plugins implementing support for other compile-to-js add to the list of “resolvable” file extensions. Gatsby supports .js and .jsx by default.


setFieldsOnGraphQLNodeType

Called during the creation of the GraphQL schema. Allows plugins to add new fields to the types created from data nodes. Many transformer plugins use this to add fields that take arguments.

  • gatsby-transformer-remark adds an “excerpt” field where the user when writing their query can specify how many characters to prune the markdown source to.
  • gatsby-transformer-sharp exposes many image transformation options as GraphQL fields.

sourceNodes

Extension point to tell plugins to source nodes.

See also the documentation for createNode.

Example

exports.sourceNodes = ({ boundActionCreators }) => {
  const { createNode } = boundActionCreators
  // Create nodes here.
}