Skip to main content

Gatsby Node API helpers

The first argument passed to each of Gatsby’s Node APIs is an object containing a set of helpers. Helpers shared by all Gatsby’s Node APIs are documented in Shared helpers section.

// in gatsby-node.js
exports.createPages = gatsbyNodeHelpers => {
  const { actions, reporter } = gatsbyNodeHelpers
  // use helpers
}

Common convention is to destructure helpers right in argument list:

// in gatsby-node.js
exports.createPages = ({ actions, reporter }) => {
  // use helpers
}

Note

Some APIs provide additional helpers. For example createPages provides graphql function. Check documentation of specific APIs in Gatsby Node APIs for details.

Shared helpers


Reference

actions Actions

Collection of functions used to programmatically modify Gatsby’s internal state.

See actions reference.

boundActionCreators Actions

Collection of functions used to programmatically modify Gatsby’s internal state.

See actions reference.

Will be removed in gatsby 3.0. Use actions instead.

cache GatsbyCache

Key-value store used to persist results of time/memory/cpu intensive tasks. All functions are async and return promises.

Fields

  • get (key: string) => Promise<any>

    Retrieve cached value

    Parameters
    • key string

      Cache key

    Return value
    Promise<any>

    Promise resolving to cached value

    Example

    const value = await cache.get(`unique-key`)
  • set (key: string, value: any) => Promise<any>

    Cache value

    Parameters
    • key string

      Cache key

    • value any

      Value to be cached

    Return value
    Promise<any>

    Promise resolving to cached value

    Example

    await cache.set(`unique-key`, value)

createContentDigest Function

(input: string | object) => string

Create a stable content digest from a string or object, you can use the result of this function to set the internal.contentDigest field on nodes. Gatsby uses the value of this field to invalidate stale data when your content changes.

Parameters

  • input string | object

Return value

string

Hash string

Example

const node = {
  ...nodeData,
  internal: {
    type: `TypeOfNode`,
    contentDigest: createContentDigest(nodeData)
  }
}

createNodeId Function

(input: string) => string

Utility function useful to generate globally unique and stable node IDs. It will generate different IDs for different plugins if they use same input.

Parameters

  • input string

Return value

string

UUIDv5 ID string

Example

const node = {
  id: createNodeId(`${backendData.type}${backendData.id}`),
  ...restOfNodeData
}

emitter Emitter

Internal event emitter / listener. Do not use, unless you absolutely must. Emitter is considered a private API and can change with any version.

getCache Function

(id: string) => GatsbyCache

Get cache instance by name - this should only be used by plugins that accept subplugins.

Parameters

  • id string

    Test

Return value

GatsbyCache

See cache section for reference.

getNode Function

(ID: string) => Node

Get single node by given ID. Don’t use this in graphql resolvers - see getNodeAndSavePathDependency.

Parameters

  • ID string

    id of the node.

Return value

Node

Single node instance.

Example

const node = getNode(id)

getNodeAndSavePathDependency Function

(ID: string, path: string) => Node

Get single node by given ID and create dependency for given path. This should be used instead of getNode in graphql resolvers to enable tracking dependencies for query results. If it’s not used Gatsby will not rerun query if node changes leading to stale query results. See Page -> Node Dependency Tracking for more details.

Parameters

  • ID string

    id of the node.

  • path string

    of the node.

Return value

Node

Single node instance.

getNodes Function

() => Node[]

Get array of all nodes.

Return value

Node[]

Array of nodes.

Example

const allNodes = getNodes()

getNodesByType Function

(Type: string) => Node[]

Get array of nodes of given type.

Parameters

  • Type string

    of nodes

Return value

Node[]

Array of nodes.

Example

const markdownNodes = getNodesByType(`MarkdownRemark`)

hasNodeChanged Function

(id: string, contentDigest: string) => boolean

Compares contentDigest of cached node with passed value to determine if node has changed.

This check is done internally in Gatsby and it’s not necessary to use it in plugins. Will be removed in gatsby 3.0.

Parameters

  • id string

    of node

  • contentDigest string

    of node

Return value

boolean

loadNodeContent Function

(node: Node) => Promise<string>

Get content for a node from the plugin that created it.

Parameters

  • node Node

Return value

Promise<string>

Example

module.exports = async function onCreateNode(
  { node, loadNodeContent, actions, createNodeId }
) {
  if (node.internal.mediaType === 'text/markdown') {
    const { createNode, createParentChildLink } = actions
    const textContent = await loadNodeContent(node)
    // process textContent and create child nodes
  }
}

pathPrefix string

Use to prefix resources URLs. pathPrefix will be either empty string or path that starts with slash and doesn’t end with slash. Check Adding a Path Prefix page for details about path prefixing.

reporter GatsbyReporter

Set of utilities to output information to user

Fields

  • info (message: string) => void
    Parameters
    • message string

      Message to display

    Return value
    void

    Example

    reporter.info(`text`)
  • warn (message: string) => void
    Parameters
    • message string

      Message to display

    Return value
    void

    Example

    reporter.warn(`text`)
  • error (message: string, error?: Error) => void
    Parameters
    • message string

      Message to display

    • error Error

      Optional error object

    Return value
    void

    Example

    reporter.error(`text`, new Error('something'))
  • panic (message: string, error?: Error) => void
    Parameters
    • message string

      Message to display

    • error Error

      Optional error object

    Return value
    void

    Example

    reporter.panic(`text`, new Error('something'))
  • panicOnBuild (message: string, error?: Error) => void
    Parameters
    • message string

      Message to display

    • error Error

      Optional error object

    Return value
    void

    Example

    reporter.panicOnBuild(`text`, new Error('something'))

store Redux.Store

Internal redux state used for application state. Do not use, unless you absolutely must. Store is considered a private API and can change with any version.

tracing GatsbyTracing

Set of utilities that allow adding more detailed tracing for plugins. Check Performance tracing page for more details.

Fields

  • tracer Opentracing.Tracer

    Global tracer instance. Check opentracing Tracer documentation for more details.

  • parentSpan Opentracing.Span

    Tracer span representing API run. Check opentracing Span documentation for more details.

  • startSpan (spanName: string) => Opentracing.Span

    Start a tracing span. The span will be created as a child of the currently running API span. This is a convenience wrapper for

    tracing.tracer.startSpan(`span-name`, { childOf: tracing.parentSpan}).
    Parameters
    • spanName string

      name of the span

    Return value
    Opentracing.Span

    Example

    exports.sourceNodes = async ({ actions, tracing }) => {
  const span = tracing.startSpan(`foo`)

  // Perform any span operations. E.g add a tag to your span
  span.setTag(`bar`, `baz`)

  // Rest of your plugin code

  span.finish()
}
Docs
Tutorials
Plugins
Blog
Showcase