Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

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.

Common convention is to destructure helpers right in argument list:

The Creating a Source Plugin tutorial explains some of the Shared helpers in more detail.

Note

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

Start building today on Netlify!

Shared helpers

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)
  • del (key: string) => Promise<void>

    Deletes cached value

    Parameters
    • key string

      Cache key

    Return value
    Promise<void>

    Promise resolving once key is deleted from cache

    Example

    await cache.del(`unique-key`)

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'))
  • verbose (message: string) => void

    Note that this method only works if the —verbose option has been passed to the CLI

    Parameters
    • message string

      Message to display

    Return value
    void

    Example

    reporter.verbose(`text`)
  • activityTimer (message: string) => ITimerReporter

    Creates a new activity timer with the provided message. Check the full return type definition here.

    Parameters
    • message string

      Timer message to display

    Return value
    ITimerReporter

    Example

    const activity = reporter.activityTimer(`Timer text`)
    
    activity.start()
    activity.setStatus(`status text`)
    activity.end()

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

actions Actions

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

See actions reference.


basePath string

This is the same as pathPrefix passed in gatsby-config.js. It’s an empty string if you don’t pass pathPrefix. When using assetPrefix, you can use this instead of pathPrefix to recieve the string you set in gatsby-config.js. It won’t include the assetPrefix.


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)
  • del (key: string) => Promise<void>

    Deletes cached value

    Parameters
    • key string

      Cache key

    Return value
    Promise<void>

    Promise resolving once key is deleted from cache

    Example

    await cache.del(`unique-key`)

(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

    id of the node

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)

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

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

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

parentSpan Opentracing.Span

Tracer span representing the passed through span from Gatsby to its plugins. Learn more: opentracing Span documentation


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. pathPrefix also becomes <assetPrefix>/<pathPrefix> when you pass both assetPrefix and pathPrefix in your gatsby-config.js.

See 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'))
  • verbose (message: string) => void

    Note that this method only works if the —verbose option has been passed to the CLI

    Parameters
    • message string

      Message to display

    Return value
    void

    Example

    reporter.verbose(`text`)
  • activityTimer (message: string) => ITimerReporter

    Creates a new activity timer with the provided message. Check the full return type definition here.

    Parameters
    • message string

      Timer message to display

    Return value
    ITimerReporter

    Example

    const activity = reporter.activityTimer(`Timer text`)
    
    activity.start()
    activity.setStatus(`status text`)
    activity.end()

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()
    }
Edit this page on GitHub
© 2023 Gatsby, Inc.