Actions

Gatsby uses Redux internally to manage state. When you implement a Gatsby API, you are passed a collection of actions (equivalent to actions bound with bindActionCreators 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.

Functions

`addThirdPartySchema`
Source

Only available in:createSchemaCustomization sourceNodes

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. Merging it in this way will easily break the main Gatsby Schema. Since we do not want that, therefore it is the user’s responsibility to make sure that it does not happen. One such way of avoiding it is by namespacing the schema.

Parameters

destructured object
- schema GraphQLSchema
  GraphQL schema to add
plugin IGatsbyPlugin
traceId string

Return value

IAddThirdPartySchema

`createFieldExtension`
Source

Only available in:createSchemaCustomization sourceNodes

Add a field extension to the GraphQL schema.

Extensions allow defining custom behavior which can be added to fields via directive (in SDL) or on the extensions prop (with Type Builders).

The extension definition takes a name, an extend function, and optional extension args for options. The extend function has to return a (partial) field config, and receives the extension options and the previous field config as arguments.

Parameters

extension GraphQLFieldExtensionDefinition
The field extension definition
plugin IGatsbyPlugin
traceId string

Return value

ThunkAction<>

Example

exports.createSchemaCustomization = ({ actions }) => {
  const { createFieldExtension } = actions
  createFieldExtension({
    name: 'motivate',
    args: {
      caffeine: 'Int'
    },
    extend(options, prevFieldConfig) {
      return {
        type: 'String',
        args: {
          sunshine: {
            type: 'Int',
            defaultValue: 0,
          },
        },
        resolve(source, args, context, info) {
          const motivation = (options.caffeine || 0) - args.sunshine
          if (motivation > 5) return 'Work! Work! Work!'
          return 'Maybe tomorrow.'
        },
      }
    },
  })
}

`createJob`
Source

DEPRECATED. Use createJobV2 instead.

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

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

Use “createJobV2” instead

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` })

`createJobV2`
Source

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

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

Parameters

job Object
A job object with name, inputPaths, outputDir and args
- name string
  The name of the job you want to execute
- inputPaths string[]
  The inputPaths that are needed to run
- outputDir string
  The directory where all files are being saved to
- args Object
  The arguments the job needs to execute
plugin Plugin

Return value

Promise<object>

Promise to see if the job is done executing

Example

createJobV2({ name: `IMAGE_PROCESSING`, inputPaths: [`something.jpeg`], outputDir: `public/static`, args: { width: 100, height: 100 } })

`createNode`
Source

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. Only fields described below are allowed in internal object. Using any type of custom fields will result in validation errors.
  - 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 chosen 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

Return value

Promise

The returned Promise resolves when all cascading onCreateNode API calls triggered by createNode have finished.

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

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 any
  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`
Source

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. Unicode characters should be passed directly and not encoded (eg. á not %C3%A1).
- matchPath string
  Path that Reach Router uses to match the page on the client side. Also see docs on matchPath
- ownerNodeId string
  The id of the node that owns this page. This is used for routing users to previews via the unstable_createNodeManifest public action. Since multiple nodes can be queried on a single page, this allows the user to tell us which node is the main node for the page. Note that the ownerNodeId must be for a node which is queried on this page via a GraphQL query.
- 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.
- defer boolean
  When set to true, Gatsby will exclude the page from the build step and instead generate it during the first HTTP request. Default value is false. Also see docs on Deferred Static Generation.
plugin Plugin
actionOptions ActionOptions

Example

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

`createParentChildLink`
Source

Creates a link between a parent and child node. This is used when you transform content from a node creating a new child node. You need to add this new child node to the children array of the parent but since you don’t have direct access to the immutable parent node, use this action instead.

Parameters

destructured object
- parent Object
  the parent node object
- child Object
  the child node object
plugin Plugin

Example

createParentChildLink({ parent: parentNode, child: childNode })

`createRedirect`
Source

Create a redirect from one page to another. Redirects work out of the box with Gatsby Cloud. Read more about working with redirects on Gatsby Cloud. If you are hosting somewhere other than Gatsby Cloud, you will need a plugin to integrate the redirect data with your hosting technology e.g. the Netlify plugin, or the Amazon S3 plugin. Alternatively, you can use this plugin to generate meta redirect html files for redirecting on any static file host.

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 on the server. If you can’t update your UI for some reason, set redirectInBrowser to true and Gatsby will handle redirecting in the client as well. You almost never need this so be sure your use case fits before enabling.
- toPath string
  URL of a created page (see createPage)
- ignoreCase boolean
  (Plugin-specific) Ignore case when looking for redirects
- 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
- conditions Object
  Specify a country or language based redirect
  - country string | string[]
    A two-letter country code based on the regional indicator symbol
  - language string | string[]
    A two-letter identifier defined by ISO 639-1
- rest

Example

// Generally you create redirects while creating pages.
exports.createPages = ({ graphql, actions }) => {
  const { createRedirect } = actions
  createRedirect({ fromPath: '/old-url', toPath: '/new-url', isPermanent: true })
  createRedirect({ fromPath: '/url', toPath: '/zn-CH/url', conditions: { language: 'zn' }})
  createRedirect({ fromPath: '/url', toPath: '/en/url', conditions: { language: ['ca', 'us'] }})
  createRedirect({ fromPath: '/url', toPath: '/ca/url', conditions: { country: 'ca' }})
  createRedirect({ fromPath: '/url', toPath: '/en/url', conditions: { country: ['ca', 'us'] }})
  createRedirect({ fromPath: '/not_so-pretty_url', toPath: '/pretty/url', statusCode: 200 })
  // Create pages here
}

`createResolverContext`
Source

Only available in:createSchemaCustomization

Make functionality available on field resolver context

Parameters

context object
Object to make available on context. When called from a plugin, the context value will be namespaced under the camel-cased plugin name without the “gatsby-” prefix
plugin IGatsbyPlugin
traceId string

Return value

ThunkAction<>

Example

const getHtml = md => remark().use(html).process(md)
exports.createSchemaCustomization = ({ actions }) => {
  actions.createResolverContext({ getHtml })
}
// The context value can then be accessed in any field resolver like this:
exports.createSchemaCustomization = ({ actions, schema }) => {
  actions.createTypes(schema.buildObjectType({
    name: 'Test',
    interfaces: ['Node'],
    fields: {
      md: {
        type: 'String!',
        async resolve(source, args, context, info) {
          const processed = await context.transformerRemark.getHtml(source.internal.contents)
          return processed.contents
        }
      }
    }
  }))
}

`createServerVisitedPage`
Source

Record that a page was visited on the server..

Parameters

chunkName string
destructured object
- id string
  the chunkName for the page component.

`createTypes`
Source

Only available in:createSchemaCustomization sourceNodes

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:
- 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, @dontInfer directives or extensions. Fields may be assigned resolver (and other option like args) with additional directives. Currently @dateformat, @link, @fileByRelativePath and @proxy are available.
Schema customization controls:
- @infer - run inference on the type and add fields that don’t exist on the
defined type to it.
- @dontInfer - don’t run any inference on the type
Extensions to add resolver options:
- @dateformat - add date formatting arguments. Accepts formatString and locale options that sets the defaults for this field
- @link - connect to a different Node. Arguments by and from, which define which field to compare to on a remote node and which field to use on the source node
- @fileByRelativePath - connect to a File node. Same arguments. The difference from link is that this normalizes the relative path to be relative from the path where source node is found.
- @proxy - in case the underlying node data contains field names with characters that are invalid in GraphQL, proxy allows to explicitly proxy those properties to fields with valid field names. Takes a from arg.
plugin IGatsbyPlugin
traceId string

Return value

ICreateTypes

Example

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

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

    """
    Author information
    """
    # Does not include automatically inferred fields
    type AuthorJson implements Node @dontInfer {
      name: String!
      birthday: Date! @dateformat(locale: "ru")
    }
  `
  createTypes(typeDefs)
}

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

`deleteNode`
Source

Delete a node

Parameters

node object
A node object. See the “createNode” action for more information about the node object details.
plugin Plugin

Example

deleteNode(node)

`deletePage`
Source

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

DEPRECATED. Use createJobV2 instead.

End a “job”.

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

Use “createJobV2” instead

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` })

`printTypeDefinitions`
Source

Only available in:createSchemaCustomization

Write GraphQL schema to file

Writes out inferred and explicitly specified type definitions. This is not the full GraphQL schema, but only the types necessary to recreate all type definitions, i.e. it does not include directives, built-ins, and derived types for filtering, sorting, pagination etc. Optionally, you can define a list of types to include/exclude. This is recommended to avoid including definitions for plugin-created types.

The first object parameter is required, however all the fields in the object are optional.

Parameters

destructured object
- path string
  The path to the output file, defaults to schema.gql
- include object
  Configure types to include
  - types string[]
    Only include these types
  - plugins string[]
    Only include types owned by these plugins
- exclude object
  Configure types to exclude
  - types string[]
    Do not include these types
  - plugins string[]
    Do not include types owned by these plugins
- withFieldTypes boolean
  Include field types, defaults to true
plugin IGatsbyPlugin
traceId string

Return value

IPrintTypeDefinitions

Example

exports.createSchemaCustomization = ({ actions }) => {
  // This code writes a GraphQL schema to a file named `schema.gql`.
  actions.printTypeDefinitions({})
}

exports.createSchemaCustomization = ({ actions }) => {
  // This code writes a GraphQL schema to a file named `schema.gql`, but this time it does not include field types.
  actions.printTypeDefinitions({ withFieldTypes: false })
}

`replaceWebpackConfig`
Source

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

`setBabelOptions`
Source

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

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:  `@emotion/babel-plugin`,
  options: {
    sourceMap: true,
  },
})

`setBabelPreset`
Source

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

DEPRECATED. Use createJobV2 instead.

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

Use “createJobV2” instead

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

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() })

`setRequestHeaders`
Source

Stores request headers for a given domain to be later used when making requests for Image CDN (and potentially other features).

Parameters

destructured object
- domain string
  The domain to store the headers for.
- headers Object
  The headers to store.
plugin Plugin

`setWebpackConfig`
Source

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

“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

node Object
A node object. See the “createNode” action for more information about the node object details.
plugin Plugin

Example

touchNode(node)

`unstable_createNodeManifest`
Source

Creates an individual node manifest. This is used to tie the unique revision state within a data source at the current point in time to a page generated from the provided node when it’s node manifest is processed.

Parameters

destructured object
- manifestId
- node
- updatedAtUTC
plugin Plugin
manifest Object
Manifest data
- manifestId string
  An id which ties the unique revision state of this manifest to the unique revision state of a data source.
- node Object
  The Gatsby node to tie the manifestId to. See the “createNode” action for more information about the node object details.
- updatedAtUTC string
  (optional) The time in which the node was last updated. If this parameter is not included, a manifest is created for every node that gets called. By default, node manifests are created for content updated in the last 30 days. To change this, set a NODE_MANIFEST_MAX_DAYS_OLD environment variable.

Example

unstable_createNodeManifest({
  manifestId: `post-id-1--updated-53154315`,
  updatedAtUTC: `2021-07-08T21:52:28.791+01:00`,
  node: {
     id: `post-id-1`
  },
})

Edit this page on GitHub

Actions

Functions

Parameters

destructured object

plugin IGatsbyPlugin

traceId string.css-zf49pv:before{content:" (optional)";color:#4084a1;font-weight:400;}

Return value

IAddThirdPartySchema

Parameters

extension GraphQLFieldExtensionDefinition

plugin IGatsbyPlugin

traceId string

Return value

ThunkAction<>

Example

Parameters

job Object

id id

plugin

Example

Parameters

job Object

name string

inputPaths string[]

outputDir string

args Object

plugin Plugin

Return value

Promise<object>

Example

Parameters

node Object

id string

parent string

children Array

internal Object

mediaType string

type string

content string

contentDigest string

description string

plugin Plugin

actionOptions ActionOptions

Return value

Promise

Example

Parameters

destructured object

node Object

name string

value any

plugin Plugin

actionOptions ActionOptions

Example

Parameters

page Object

path string

matchPath string

ownerNodeId string

component string

context Object

defer boolean

plugin Plugin

actionOptions ActionOptions

Example

Parameters

destructured object

parent Object

child Object

plugin Plugin

Example

Parameters

redirect Object

fromPath string

isPermanent boolean

redirectInBrowser boolean

toPath string

ignoreCase boolean

force boolean

statusCode number

`plugin` IGatsbyPlugin

`traceId` string

`extension` GraphQLFieldExtensionDefinition

`plugin` IGatsbyPlugin

`traceId` string

`job` Object

`id` id

`plugin`

`job` Object

`name` string

`inputPaths` string[]

`outputDir` string

`args` Object

`plugin` Plugin

`node` Object

`id` string

`parent` string

`children` Array

`internal` Object

`mediaType` string

`type` string

`content` string

`contentDigest` string

`description` string

`plugin` Plugin

`actionOptions` ActionOptions

`node` Object

`name` string

`value` any

`plugin` Plugin

`actionOptions` ActionOptions

`page` Object

`path` string

`matchPath` string

`ownerNodeId` string

`component` string

`context` Object

`defer` boolean

`plugin` Plugin

`actionOptions` ActionOptions

`parent` Object

`child` Object

`plugin` Plugin

`redirect` Object

`fromPath` string

`isPermanent` boolean

`redirectInBrowser` boolean

`toPath` string

`ignoreCase` boolean

`force` boolean

`statusCode` number

`conditions` Object

`country` string | string[]

`language` string | string[]

`rest`

`context` object

`plugin` IGatsbyPlugin

`traceId` string

`chunkName` string

`id` string

`types` string | GraphQLOutputType | GatsbyGraphQLType | string[] | GraphQLOutputType[] | GatsbyGraphQLType[]

`plugin` IGatsbyPlugin

`traceId` string

`node` object

`plugin` Plugin

`page` Object

`path` string

`component` string

`job` Object

`id` id

`plugin`

`path` string

`include` object

`types` string[]

`plugins` string[]

`exclude` object

`types` string[]

`plugins` string[]

`withFieldTypes` boolean

`plugin` IGatsbyPlugin