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

`GatsbyCache`

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

`GatsbyReporter`

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

`GatsbyTracing`

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.

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

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

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

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

`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

Node API Helpers

Note

Shared helpers

.css-ceuaa7{margin-right:0.75rem;display:inline-block;}GatsbyCache

Fields

Parameters

key string

Return value

Promise<any>

Example

set (key: string, value: any) => Promise<any>

Parameters

key string

value any

Return value

Promise<any>

Example

del (key: string) => Promise<void>

Parameters

key string

Return value

Promise<void>

Example

GatsbyReporter

Fields

info (message: string) => void

Parameters

message string

Return value

void

Example

warn (message: string) => void

Parameters

message string

Return value

void

Example

error (message: string, error?: Error) => void

Parameters

message string

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

Return value

void

Example

panic (message: string, error?: Error) => void

Parameters

message string

error Error

Return value

void

Example

panicOnBuild (message: string, error?: Error) => void

Parameters

message string

error Error

Return value

void

Example

verbose (message: string) => void

Parameters

message string

Return value

void

Example

activityTimer (message: string) => ITimerReporter

Parameters

message string

Return value

ITimerReporter

Example

GatsbyTracing

Fields

tracer Opentracing.Tracer

parentSpan Opentracing.Span

startSpan (spanName: string) => Opentracing.Span

Parameters

spanName string

Return value

Opentracing.Span

Example

`GatsbyCache`

`key` string

`set` (key: string, value: any) => Promise<any>

`key` string

`value` any

`del` (key: string) => Promise<void>

`key` string

`GatsbyReporter`

`info` (message: string) => void

`message` string

`warn` (message: string) => void

`message` string

`error` (message: string, error?: Error) => void

`message` string

`error` Error

`panic` (message: string, error?: Error) => void

`message` string

`error` Error

`panicOnBuild` (message: string, error?: Error) => void

`message` string

`error` Error

`verbose` (message: string) => void

`message` string

`activityTimer` (message: string) => ITimerReporter

`message` string

`GatsbyTracing`

`tracer` Opentracing.Tracer

`parentSpan` Opentracing.Span

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

`spanName` string

`actions` Actions

`basePath` string

`cache` GatsbyCache

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

`key` string

`set` (key: string, value: any) => Promise<any>

`key` string

`value` any

`del` (key: string) => Promise<void>

`key` string

`createContentDigest` Function

`input` string | object

`createNodeId` Function

`input` string

`emitter` Emitter

`getCache` Function

`id` string

`getNode` Function

`ID` string

`getNodeAndSavePathDependency` Function

`ID` string

`path` string

`getNodes` Function

`getNodesByType` Function

`Type` string

`loadNodeContent` Function

`node` Node