Gatsby Node APIs

Introduction

Gatsby gives plugins and site builders many APIs for building your site. Code in the file gatsby-node.js/gatsby-node.ts is run once in the process of building your site. You can use its APIs to create pages dynamically, add data into GraphQL, or respond to events during the build lifecycle. To use the Gatsby Node APIs, create a file named gatsby-node.js/gatsby-node.ts in the root of your site. Export any of the APIs you wish to use in this file.

You can author the file in JavaScript (CommonJS or ES Modules (ESM) syntax) or TypeScript.

Every Gatsby Node API gets passed a set of helper functions. These let you access several methods like reporting, or perform actions like creating new pages.

An example gatsby-node.js file that implements two APIs, onPostBuild, and createPages.

The TypeScript and Gatsby documentation shows how to set up a gatsby-node file in TypeScript.

Read the ES Modules (ESM) and Gatsby documentation if you don’t want to use CommonJS syntax.

Async vs. sync work

If your plugin performs async operations (disk I/O, database access, calling remote APIs, etc.) you must either return a promise (explicitly using Promise API or implicitly using async/await syntax) 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. See Debugging Async Lifecycles for more info.

If your plugin does not do async work, you can return directly.

Start building today on Netlify!

APIs

`createPages`

Create pages dynamically. 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.

You can also fetch data from remote or local sources to create pages.

Parameters

destructured object
See the documentation for Node API Helpers for more details
- actions Actions
  See the list of documented actions
  - createPage function
    Documentation for this action
- graphql function
  : Query GraphQL API. See examples here
- reporter GatsbyReporter
  Log issues. See GatsbyReporter documentation for more details

Return value

Promise<void>

No return value required, but the caller will await any promise that’s returned

Example

const path = require(`path`)

exports.createPages = ({ graphql, actions }) => {
  const { createPage } = actions
  const blogPostTemplate = path.resolve(`src/templates/blog-post.js`)
  // Query for markdown nodes to use in creating pages.
  // You can query for whatever data you want to create pages for e.g.
  // products, portfolio items, landing pages, etc.
  // Variables can be added as the second function parameter
  return graphql(`
    query loadPagesQuery ($limit: Int!) {
      allMarkdownRemark(limit: $limit) {
        edges {
          node {
            frontmatter {
              slug
            }
          }
        }
      }
    }
  `, { limit: 1000 }).then(result => {
    if (result.errors) {
      throw result.errors
    }

    // Create blog post pages.
    result.data.allMarkdownRemark.edges.forEach(edge => {
      createPage({
        // Path for this page — required
        path: `${edge.node.frontmatter.slug}`,
        component: blogPostTemplate,
        context: {
          // Add optional context data to be inserted
          // as props into the page component.
          //
          // The context data can also be used as
          // arguments to the page GraphQL query.
          //
          // The page "path" is always available as a GraphQL
          // argument.
        },
      })
    })
  })
}

`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 plugin gatsby-plugin-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.

`createResolvers`
Source

Add custom field resolvers to the GraphQL schema.

Allows adding new fields to types by providing field configs, or adding resolver functions to existing fields.

Things to note:

Overriding field types is disallowed, instead use the createTypes action. In case of types added from third-party schemas, where this is not possible, overriding field types is allowed.
New fields will not be available on filter and sort input types. Extend types defined with createTypes if you need this.
In field configs, types can be referenced as strings.
When extending a field with an existing field resolver, the original resolver function is available from info.originalResolver.
The createResolvers API is called as the last step in schema generation. Thus, an intermediate schema is made available on the intermediateSchema property. In resolver functions themselves, it is recommended to access the final built schema from info.schema.
Gatsby’s data layer, including all internal query capabilities, is exposed on context.nodeModel. The node store can be queried directly with findOne, getNodeById and getNodesByIds, while more advanced queries can be composed with findAll.
It is possible to add fields to the root Query type.
When using the first resolver argument (source in the example below, often also called parent or root), take care of the fact that field resolvers can be called more than once in a query, e.g. when the field is present both in the input filter and in the selection set. This means that foreign-key fields on source can be either resolved or not-resolved.

For fuller examples, see using-type-definitions.

Parameters

destructured object
- intermediateSchema GraphQLSchema
  Current GraphQL schema
- createResolvers function
  Add custom resolvers to GraphQL field configs
$1 object
- resolvers object
  An object map of GraphQL type names to custom resolver functions
- options object
  Optional createResolvers options
  - ignoreNonexistentTypes object
    Silences the warning when trying to add resolvers for types that don’t exist. Useful for optional extensions.

Example

exports.createResolvers = ({ createResolvers }) => {
  const resolvers = {
    Author: {
      fullName: {
        resolve: (source, args, context, info) => {
          return source.firstName + source.lastName
        }
      },
    },
    Query: {
      allRecentPosts: {
        type: [`BlogPost`],
        resolve: async (source, args, context, info) => {
          const { entries } = await context.nodeModel.findAll({ type: `BlogPost` })
          return entries.filter(
            post => post.publishedAt > Date.UTC(2018, 0, 1)
          )
        }
      }
    }
  }
  createResolvers(resolvers)
}

`createSchemaCustomization`

Customize Gatsby’s GraphQL schema by creating type definitions, field extensions or adding third-party schemas.

The createTypes, createFieldExtension and addThirdPartySchema actions are only available in this API. For details on their usage please refer to the actions documentation.

This API runs immediately before schema generation. For modifications of the generated schema, e.g. to customize added third-party types, use the createResolvers API.

Parameters

destructured object
- actions object
  - createTypes object
  - createFieldExtension object
  - addThirdPartySchema object

Example

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  createFieldExtension({
    name: 'shout',
    extend: () => ({
      resolve(source, args, context, info) {
        return String(source[info.fieldName]).toUpperCase()
      }
    })
  })

  const typeDefs = `
    type MarkdownRemark implements Node @dontInfer {
      frontmatter: Frontmatter
    }
    type Frontmatter {
      title: String!
      tagline: String @shout
      date: Date @dateformat
      image: File @fileByRelativePath
    }
  `
  createTypes(typeDefs)
}

`onCreateBabelConfig`

Let plugins extend/mutate the site’s Babel configuration by calling setBabelPlugin or setBabelPreset.

Parameters

destructured object
- stage string
  The current build stage. One of ‘develop’, ‘develop-html’, ‘build-javascript’, or ‘build-html’
- actions object
options object
The Babel configuration

Example

exports.onCreateBabelConfig = ({ actions }) => {
  actions.setBabelPlugin({
    name: `babel-plugin-that-i-like`,
    options: {}
  })
}

`onCreateDevServer`

Run when the gatsby develop server is started. It can be used for adding proxies and Express middleware to the server.

Parameters

destructured object
- app Express
  The Express app used to run the dev server

Example

exports.onCreateDevServer = ({ app }) => {
  app.get('/hello', function (req, res) {
    res.send('hello world')
  })
}

`onCreateNode`
Source

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

The Creating a Source Plugin tutorial demonstrates a way a plugin or site might use this API.

Example

exports.onCreateNode = ({ node, actions }) => {
  const { createNode, createNodeField } = actions
  // 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.

There is a mechanism in Gatsby to prevent calling onCreatePage for pages created by the same gatsby-node.js to avoid infinite loops/callback.

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

`onCreateWebpackConfig`
Source

Let plugins extend/mutate the site’s webpack configuration. This method can be used by any Gatsby site, app, or plugin, not just plugins.

See also the documentation for setWebpackConfig.

Parameters

destructured object
- stage string
  The current build stage. One of ‘develop’, ‘develop-html’, ‘build-javascript’, or ‘build-html’
- getConfig function
  Returns the current webpack config
- rules object
  A set of preconfigured webpack config rules
- loaders object
  A set of preconfigured webpack config loaders
- plugins object
  A set of preconfigured webpack config plugins
- actions object

Example

exports.onCreateWebpackConfig = ({
 stage, getConfig, rules, loaders, actions
}) => {
  actions.setWebpackConfig({
    module: {
      rules: [
        {
          test: 'my-css',
          use: [loaders.style(), loaders.css()]
        },
      ],
    },
  });
}

`onPluginInit`

Lifecycle executed in each process (one time per process). Used to store actions etc for later use.

Example

let createJobV2
exports.onPluginInit = ({ actions }) => {
  // store job creation action to use it later
  createJobV2 = actions.createJobV2
}

`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.

Example

exports.onPostBuild = ({ reporter, basePath, pathPrefix }) => {
 reporter.info(
  `Site was built with basePath: ${basePath} & pathPrefix: ${pathPrefix}`
 );
};

`onPreBootstrap`

Called once Gatsby has initialized itself and is ready to bootstrap your site.

`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-sharp and gatsby-source-contentful for examples.

`onPreInit`

The first API called during Gatsby execution, runs as soon as plugins are loaded, before cache initialization and bootstrap preparation.

Parameters

destructured object
- actions object

Example

exports.onPreInit = ({ actions }) => {

}

`pluginOptionsSchema`

Run during the bootstrap phase. Plugins can use this to define a schema for their options using Joi to validate the options users pass to the plugin.

Parameters

destructured object
- Joi Joi
  The instance of Joi to define the schema

Example

exports.pluginOptionsSchema = ({ Joi }) => {
  return Joi.object({
    // Validate that the anonymize option is defined by the user and is a boolean
    anonymize: Joi.boolean().required(),
  })
}

`preprocessSource`

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

`resolvableExtensions`

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

Return value

string[]

array of extensions

`setFieldsOnGraphQLNodeType`
Source

Called during the creation of the GraphQL schema. Allows plugins to add new fields to the types created from data nodes. It will be called separately for each type.

This function should return an object in the shape of GraphQLFieldConfigMap which will be appended to fields inferred by Gatsby from data nodes.

Note: Import GraphQL types from gatsby/graphql and don’t add the graphql package to your project/plugin dependencies to avoid Schema must contain unique named types but contains multiple types named errors. gatsby/graphql exports all builtin GraphQL types as well as the GraphQLJSON type.

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.

Parameters

destructured object
- type object
  Object containing name and nodes

Example

import { GraphQLString } from "gatsby/graphql"

exports.setFieldsOnGraphQLNodeType = ({ type }) => {
  if (type.name === `File`) {
    return {
      newField: {
        type: GraphQLString,
        args: {
          myArgument: {
            type: GraphQLString,
          }
        },
        resolve: (source, fieldArgs) => {
          return `Id of this node is ${source.id}.
                  Field was called with argument: ${fieldArgs.myArgument}`
        }
      }
    }
  }

  // by default return empty object
  return {}
}

`shouldOnCreateNode`

Called before scheduling a onCreateNode callback for a plugin. If it returns falsy then Gatsby will not schedule the onCreateNode callback for this node for this plugin. Note: this API does not receive the regular api that other callbacks get as first arg.

Example

exports.shouldOnCreateNode = ({node}, pluginOptions) => node.internal.type === 'Image'

`sourceNodes`

Extension point to tell plugins to source nodes. This API is called during the Gatsby bootstrap sequence. Source plugins use this hook to create nodes. This API is called exactly once per plugin (and once for your site’s gatsby-config.js file). If you define this hook in gatsby-node.js it will be called exactly once after all of your source plugins have finished creating nodes.

The Creating a Source Plugin tutorial demonstrates a way a plugin or site might use this API.

See also the documentation for createNode.

Example

exports.sourceNodes = ({ actions, createNodeId, createContentDigest }) => {
  const { createNode } = actions

  // Data can come from anywhere, but for now create it manually
  const myData = {
    key: 123,
    foo: `The foo field of my node`,
    bar: `Baz`
  }

  const nodeContent = JSON.stringify(myData)

  const nodeMeta = {
    id: createNodeId(`my-data-${myData.key}`),
    parent: null,
    children: [],
    internal: {
      type: `MyNodeType`,
      mediaType: `text/html`,
      content: nodeContent,
      contentDigest: createContentDigest(myData)
    }
  }

  const node = Object.assign({}, myData, nodeMeta)
  createNode(node)
}

Edit this page on GitHub

Gatsby Node APIs

Introduction

Async vs. sync work

APIs

.css-ceuaa7{margin-right:0.75rem;display:inline-block;}createPages

Parameters

destructured object

createPage function

graphql function

reporter GatsbyReporter

Return value

Promise<void>

Example

Parameters

destructured object

intermediateSchema GraphQLSchema

createResolvers function

$1 object

resolvers object

options object

ignoreNonexistentTypes object

Example

Parameters

destructured object

actions object

createTypes object

createFieldExtension object

addThirdPartySchema object

Example

Parameters

destructured object

stage string

actions object

options object

Example

Parameters

destructured object

app Express

Example

Example

Parameters

destructured object

stage string

getConfig function

rules object

loaders object

plugins object

actions object

Example

Example

Example

Parameters

destructured object

actions object

Example

Parameters

destructured object

Joi Joi

Example

Return value

string[]

Parameters

destructured object

type object

Example

Example

Example

`createPages`

`createPage` function

`graphql` function

`reporter` GatsbyReporter

`intermediateSchema` GraphQLSchema

`createResolvers` function

`$1` object

`resolvers` object

`options` object

`ignoreNonexistentTypes` object

`actions` object

`createTypes` object

`createFieldExtension` object

`addThirdPartySchema` object

`stage` string

`actions` object

`options` object

`app` Express

`stage` string

`getConfig` function

`rules` object

`loaders` object

`plugins` object

`actions` object

`actions` object

`Joi` Joi

`type` object