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

`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

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 choosen 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. The raw content of the node. Can be excluded if it’d require a lot of memory to load in which case you must define a loadNodeContent function for this node.

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.

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

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.

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

`createParentChildLink`

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

Example

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

`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}[default=false]

This is a permanent redirect; defaults to temporary

redirectInBrowser {boolean}[default=false]

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 {null}

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

`deleteNode`

Delete a node

Parameters

options {null}

args {null}

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

Example

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

`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

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

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.

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.

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

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

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

`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 {null}

destructured object

nodeId {string}

The id of a node

Example

touchNode({ nodeId: `a-node-id` })