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
}
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).
GraphQL schema to add
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.
A job object with at least an id set
The id of the job
createJob({ id: `write file id: 123`, fileName: `something.jpeg` })
createNode
Create a new node.
a node object
The node’s ID. Must be globally unique.
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
.
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
.
node fields that aren’t generally interesting to consumers of node data but are very useful for plugin writers and Gatsby core.
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
.
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.
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.
the digest for the content of this node. Helps Gatsby avoid doing extra work on data that hasn’t changed.
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.
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.
the target node object
the name for the field
the value for the field
[deprecated] the name for the field
[deprecated] the value for the field
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.
a page object
Any valid URL. Must start with a forward slash
The absolute path to the component for this page
Context data for this page. Passed as props
to the component this.props.pageContext
as well as to the graphql query
as graphql arguments.
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.
the parent node object
the child node object
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.
Redirect data
Any valid URL. Must start with a forward slash
This is a permanent redirect; defaults to temporary
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.
URL of a created page (see createPage
)
(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
(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
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
the node object
deleteNode({node: node})
deletePage
Delete a page
a page object
The path of the page
The absolute path to the page component
deletePage(page)
endJob
End a “job”.
Gatsby doesn’t finish its bootstrap until all jobs are ended.
A job object with at least an id set
The id of the job
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
.
complete webpack config
setBabelOptions
Set top-level Babel options. Plugins and presets will be ignored. Use setBabelPlugin and setBabelPreset for this.
An options object in the shape of a normal babelrc JavaScript object
setBabelOptions({
options: {
sourceMaps: `inline`,
}
})
setBabelPlugin
Add new plugins or merge options into existing Babel plugins.
A config object describing the Babel plugin to be added.
The name of the Babel plugin
Options to pass to the Babel plugin.
setBabelPlugin({
name: `babel-plugin-emotion`,
options: {
sourceMap: true,
},
})
setBabelPreset
Add new presets or merge options into existing Babel presets.
A config object describing the Babel plugin to be added.
The name of the Babel preset.
Options to pass to the Babel preset.
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.
A job object with at least an id set
The id of the job
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.
An object with arbitrary values set
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()
.
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.
The id of a node
touchNode({ nodeId: `a-node-id` })