Skip to main content

Actions

Gatsby uses Redux internally to manage state. When you implement a Gatsby API, you are passed a collection of actions (equivalent to boundActionCreators in redux) which you can use to manipulate state on your site.

The object actions contains the functions and these can be individually extracted by using ES6 object destructuring.

// For function createNodeField
exports.onCreateNode = ({ node, getNode, actions }) => {
  const { createNodeField } = actions
}

Functions

Reference

actions

All action creators wrapped with a dispatch.

addThirdPartySchema

Add a third-party schema to be merged into main schema. Schema has to be a graphql-js GraphQLSchema object.

This schema is going to be merged as-is. This can easily break the main Gatsby schema, so it’s user’s responsibility to make sure it doesn’t happen (by eg namespacing the schema).

Parameters

  • destructured object
    • schema GraphQLSchema

      GraphQL schema to add

  • plugin Plugin
  • traceId string

boundActionCreators

All action creators wrapped with a dispatch. - DEPRECATED

createJob

Create a “job”. This is a long-running process that are generally started as side-effects to GraphQL queries. gatsby-plugin-sharp uses this for example.

Gatsby doesn’t finish its bootstrap until all jobs are ended.

Parameters

  • job Object

    A job object with at least an id set

    • id id

      The id of the job

  • plugin

Example

createJob({ id: `write file id: 123`, fileName: `something.jpeg` })

createNode

Create a new node.

Parameters

  • node Object

    a node object

    • id string

      The node’s ID. Must be globally unique.

    • parent string

      The ID of the parent’s node. If the node is derived from another node, set that node as the parent. Otherwise it can just be null.

    • children Array

      An array of children node IDs. If you’re creating the children nodes while creating the parent node, add the children node IDs here directly. If you’re adding a child node to a parent node created by a plugin, you can’t mutate this value directly to add your node id, instead use the action creator createParentChildLink.

    • internal Object

      node fields that aren’t generally interesting to consumers of node data but are very useful for plugin writers and Gatsby core.

      • mediaType string

        An optional field to indicate to transformer plugins that your node has raw content they can transform. Use either an official media type (we use mime-db as our source (https://www.npmjs.com/package/mime-db) or a made-up one if your data doesn’t fit in any existing bucket. Transformer plugins use node media types for deciding if they should transform a node into a new one. E.g. markdown transformers look for media types of text/markdown.

      • type string

        An arbitrary globally unique type chosen by the plugin creating the node. Should be descriptive of the node as the type is used in forming GraphQL types so users will query for nodes based on the type choosen here. Nodes of a given type can only be created by one plugin.

      • content string

        An optional field. This is rarely used. It is used when a source plugin sources data it doesn’t know how to transform e.g. a markdown string pulled from an API. The source plugin can defer the transformation to a specialized transformer plugin like gatsby-transformer-remark. This content field holds the raw content (so for the markdown case, the markdown string).

        Data that’s already structured should be added to the top-level of the node object and not added here. You should not JSON.stringify your node’s data here.

        If the content is very large and can be lazy-loaded, e.g. a file on disk, you can define a loadNodeContent function for this node and the node content will be lazy loaded when it’s needed.

      • contentDigest string

        the digest for the content of this node. Helps Gatsby avoid doing extra work on data that hasn’t changed.

      • description string

        An optional field. Human readable description of what this node represent / its source. It will be displayed when type conflicts are found, making it easier to find and correct type conflicts.

  • plugin Plugin
  • actionOptions ActionOptions

Example

createNode({
  // Data for the node.
  field1: `a string`,
  field2: 10,
  field3: true,
  ...arbitraryOtherData,

  // Required fields.
  id: `a-node-id`,
  parent: `the-id-of-the-parent-node`, // or null if it's a source node without a parent
  children: [],
  internal: {
    type: `CoolServiceMarkdownField`,
    contentDigest: crypto
      .createHash(`md5`)
      .update(JSON.stringify(fieldData))
      .digest(`hex`),
    mediaType: `text/markdown`, // optional
    content: JSON.stringify(fieldData), // optional
    description: `Cool Service: "Title of entry"`, // optional
  }
})

createNodeField

Extend another node. The new node field is placed under the fields key on the extended node object.

Once a plugin has claimed a field name the field name can’t be used by other plugins. Also since nodes are immutable, you can’t mutate the node directly. So to extend another node, use this.

Parameters

  • destructured object
    • node Object

      the target node object

    • name string

      the name for the field

    • value string

      the value for the field

    • fieldName string

      [deprecated] the name for the field

    • fieldValue string

      [deprecated] the value for the field

  • plugin Plugin
  • actionOptions ActionOptions

Example

createNodeField({
  node,
  name: `happiness`,
  value: `is sweet graphql queries`
})

// The field value is now accessible at node.fields.happiness

createPage

Create a page. See the guide on creating and modifying pages for detailed documentation about creating pages.

Parameters

  • page Object

    a page object

    • path string

      Any valid URL. Must start with a forward slash

    • component string

      The absolute path to the component for this page

    • context Object

      Context data for this page. Passed as props to the component this.props.pageContext as well as to the graphql query as graphql arguments.

  • plugin Plugin
  • actionOptions ActionOptions

Example

createPage({
  path: `/my-sweet-new-page/`,
  component: path.resolve(`./src/templates/my-sweet-new-page.js`),
  // The context is passed as props to the component as well
  // as into the component's GraphQL query.
  context: {
    id: `123456`,
  },
})

createRedirect

Create a redirect from one page to another. Server redirects don’t work out of the box. You must have a plugin setup to integrate the redirect data with your hosting technology e.g. the Netlify plugin, or the Amazon S3 plugin.

Parameters

  • redirect Object

    Redirect data

    • fromPath string

      Any valid URL. Must start with a forward slash

    • isPermanent boolean

      This is a permanent redirect; defaults to temporary

    • redirectInBrowser boolean

      Redirects are generally for redirecting legacy URLs to their new configuration. If you can’t update your UI for some reason, set redirectInBrowser to true and Gatsby will handle redirecting in the client as well.

    • toPath string

      URL of a created page (see createPage)

    • force boolean

      (Plugin-specific) Will trigger the redirect even if the fromPath matches a piece of content. This is not part of the Gatsby API, but implemented by (some) plugins that configure hosting provider redirects

    • statusCode number

      (Plugin-specific) Manually set the HTTP status code. This allows you to create a rewrite (status code 200) or custom error page (status code 404). Note that this will override the isPermanent option which also sets the status code. This is not part of the Gatsby API, but implemented by (some) plugins that configure hosting provider redirects

    • rest

Example

createRedirect({ fromPath: '/old-url', toPath: '/new-url', isPermanent: true })
createRedirect({ fromPath: '/url', toPath: '/zn-CH/url', Language: 'zn' })
createRedirect({ fromPath: '/not_so-pretty_url', toPath: '/pretty/url', statusCode: 200 })

createTypes

Add type definitions to the GraphQL schema.

Parameters

  • types string | GraphQLOutputType | GatsbyGraphQLType | string[] | GraphQLOutputType[] | GatsbyGraphQLType[]

    Type definitions

    Type definitions can be provided either as graphql-js types, in GraphQL schema definition language (SDL) or using Gatsby Type Builders available on the schema API argument.

    Things to note:

    • needs to be called before schema generation. It is recommended to use createTypes in the sourceNodes API.
    • type definitions targeting node types, i.e. MarkdownRemark and others added in sourceNodes or onCreateNode APIs, need to implement the Node interface. Interface fields will be added automatically, but it is mandatory to label those types with implements Node.
    • by default, explicit type definitions from createTypes will be merged with inferred field types, and default field resolvers for Date (which adds formatting options) and File (which resolves the field value as a relativePath foreign-key field) are added. This behavior can be customised with @infer and @dontInfer directives, and their noDefaultResolvers argument.
  • plugin Plugin
  • traceId string

Example

exports.sourceNodes = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    """
    Markdown Node
    """
    type MarkdownRemark implements Node {
      frontmatter: Frontmatter!
    }

    """
    Markdown Frontmatter
    """
    type Frontmatter {
      title: String!
      author: AuthorJson!
      date: Date!
      published: Boolean!
      tags: [String!]!
    }

    """
    Author information
    """
    # Does not include automatically inferred fields
    type AuthorJson implements Node @dontInfer(noFieldResolvers: true) {
      name: String!
      birthday: Date! # no default resolvers for Date formatting added
    }
  `
  createTypes(typeDefs)
}

// using Gatsby Type Builder API
exports.sourceNodes = ({ actions, schema }) => {
  const { createTypes } = actions
  const typeDefs = [
    schema.buildObjectType({
      name: 'MarkdownRemark',
      fields: {
        frontmatter: 'Frontmatter!'
      },
      interfaces: ['Node'],
    }),
    schema.buildObjectType({
      name: 'Frontmatter',
      fields: {
        title: {
          type: 'String!',
          resolve(parent) {
            return parent.title || '(Untitled)'
          }
        },
        author: 'AuthorJson!',
        date: 'Date!',
        published: 'Boolean!',
        tags: '[String!]!',
      }
    })
  ]
  createTypes(typeDefs)
}

deleteNode

Delete a node

Parameters

  • options
  • plugin Plugin
  • args
  • destructured object
    • node object

      the node object

Example

deleteNode({node: node})

deletePage

Delete a page

Parameters

  • page Object

    a page object

    • path string

      The path of the page

    • component string

      The absolute path to the page component

Example

deletePage(page)

endJob

End a “job”.

Gatsby doesn’t finish its bootstrap until all jobs are ended.

Parameters

  • job Object

    A job object with at least an id set

    • id id

      The id of the job

  • plugin

Example

endJob({ id: `write file id: 123` })

maybeAddPathPrefix

Check if path is absolute and add pathPrefix in front if it’s not

Parameters

  • path
  • pathPrefix

replaceWebpackConfig

Completely replace the webpack config for the current stage. This can be dangerous and break Gatsby if certain configuration options are changed.

Generally only useful for cases where you need to handle config merging logic yourself, in which case consider using webpack-merge.

Parameters

  • config Object

    complete webpack config

  • plugin

schemaFieldName

Normalized name of the field that will be used in schema

setBabelOptions

Set top-level Babel options. Plugins and presets will be ignored. Use setBabelPlugin and setBabelPreset for this.

Parameters

  • options Object
  • plugin
  • config Object

    An options object in the shape of a normal babelrc JavaScript object

Example

setBabelOptions({
  options: {
    sourceMaps: `inline`,
  }
})

setBabelPlugin

Add new plugins or merge options into existing Babel plugins.

Parameters

  • config Object

    A config object describing the Babel plugin to be added.

    • name string

      The name of the Babel plugin

    • options Object

      Options to pass to the Babel plugin.

  • plugin

Example

setBabelPlugin({
  name:  `babel-plugin-emotion`,
  options: {
    sourceMap: true,
  },
})

setBabelPreset

Add new presets or merge options into existing Babel presets.

Parameters

  • config Object

    A config object describing the Babel plugin to be added.

    • name string

      The name of the Babel preset.

    • options Object

      Options to pass to the Babel preset.

  • plugin

Example

setBabelPreset({
  name: `@babel/preset-react`,
  options: {
    pragma: `Glamor.createElement`,
  },
})

setJob

Set (update) a “job”. Sometimes on really long running jobs you want to update the job as it continues.

Parameters

  • job Object

    A job object with at least an id set

    • id id

      The id of the job

  • plugin

Example

setJob({ id: `write file id: 123`, progress: 50 })

setPluginStatus

Set plugin status. A plugin can use this to save status keys e.g. the last it fetched something. These values are persisted between runs of Gatsby.

Parameters

  • status Object

    An object with arbitrary values set

  • plugin Plugin

Example

setPluginStatus({ lastFetched: Date.now() })

setWebpackConfig

Merge additional configuration into the current webpack config. A few configurations options will be ignored if set, in order to try prevent accidental breakage. Specifically, any change to entry, output, target, or resolveLoaders will be ignored.

For full control over the webpack config, use replaceWebpackConfig().

Parameters

  • config Object

    partial webpack config, to be merged into the current one

  • plugin

touchNode

“Touch” a node. Tells Gatsby a node still exists and shouldn’t be garbage collected. Primarily useful for source plugins fetching nodes from a remote system that can return only nodes that have updated. The source plugin then touches all the nodes that haven’t updated but still exist so Gatsby knows to keep them.

Parameters

  • options
  • plugin Plugin
  • destructured object
    • nodeId string

      The id of a node

Example

touchNode({ nodeId: `a-node-id` })
Docs
Tutorial
Plugins
Blog
Showcase