Gatsby Node Helpers

Common errors

• TypeError: createNode is not a function

  cause `createNode` was not properly destructured from `actions` in Gatsby's Node APIs.
  fix Ensure `const { actions } = gatsbyArgs; const { createNode } = actions;` or directly `gatsbyArgs.actions.createNode(node)`.

• ReferenceError: createNodeHelpers is not defined

  cause `createNodeHelpers` was not imported or was imported incorrectly (e.g., CommonJS `require` in an ESM context).
  fix Use `import { createNodeHelpers } from 'gatsby-node-helpers'` at the top of your `gatsby-node.js` or `gatsby-node.ts` file.

• Cannot find name 'GatsbyNode' / Property 'sourceNodes' does not exist on type 'GatsbyNode'

  cause Missing or incorrect Gatsby TypeScript types, or an outdated Gatsby version not matching the type definitions.
  fix Install `@types/gatsby` (`npm install --save-dev @types/gatsby`) and ensure your `gatsby` peer dependency meets the `gatsby-node-helpers` requirements (e.g., `>=2.29`).

Warnings

• breaking The `generateNodeId` utility (used internally by `createNodeFactory`) now camelCases the node's type. This changes the generated ID format for node types that previously used underscores or kebab-case.
  Fix: If you relied on the exact string format of generated node IDs for types containing non-camelCase characters (e.g., `shareable_link`), update any hardcoded references or logic that expects the old format. The new format will camelCase such types (e.g., `ShareableLink`).
• gotcha When using `createNodeFactory` with an async middleware function, ensure you `await` the result of the factory call before passing it to `createNode`.
  Fix: If your `createNodeFactory` middleware is `async`, make sure to use `const myNode = await MyNodeType(nodeData)` instead of `const myNode = MyNodeType(nodeData)` to correctly resolve the promise before calling `createNode(myNode)`.
• gotcha The `createNodeHelpers` function requires Gatsby's `createNodeId` and `createContentDigest` functions from the `gatsbyArgs` object passed to Gatsby's Node APIs (like `sourceNodes`).
  Fix: Always pass `gatsbyArgs.createNodeId` and `gatsbyArgs.createContentDigest` when initializing `createNodeHelpers`. Example: `createNodeHelpers({ typePrefix: 'MyPrefix', createNodeId, createContentDigest })`.

Install

• npm install gatsby-node-helpers npm
• yarn add gatsby-node-helpers yarn
• pnpm add gatsby-node-helpers pnpm

Imports

• createNodeHelpers
  wrong:

  const { createNodeHelpers } = require('gatsby-node-helpers')

  correct:

  import { createNodeHelpers } from 'gatsby-node-helpers'

  This is the primary factory function to initialize the helpers. It's intended for ESM usage in `gatsby-node.ts` or `gatsby-node.js`.
• createNodeFactory
  wrong:

  import { createNodeFactory } from 'gatsby-node-helpers'

  correct:

  const ProductNode = nodeHelpers.createNodeFactory('Product')

  createNodeFactory is a method returned by an instance of `createNodeHelpers`, not a direct export from the package.
• GatsbyNodeHelpers
  wrong:

  import { GatsbyNodeHelpers } from 'gatsby-node-helpers'

  correct:

  import type { GatsbyNodeHelpers } from 'gatsby-node-helpers'

  This is a TypeScript type definition for the object returned by `createNodeHelpers` for better type inference and safety.

Quickstart

Demonstrates initializing `createNodeHelpers` and using `createNodeFactory` to prepare product data for Gatsby's `createNode` action within the `sourceNodes` API.

import * as gatsby from 'gatsby'
import { createNodeHelpers } from 'gatsby-node-helpers'

interface MyProduct {
  id: string;
  name: string;
  price: number;
}

// Simulate fetching product data
async function getAllProducts(): Promise<MyProduct[]> {
  return [
    { id: 'p1', name: 'Product A', price: 29.99 },
    { id: 'p2', name: 'Product B', price: 49.99 }
  ]
}

export const sourceNodes: gatsby.GatsbyNode['sourceNodes'] = async (
  gatsbyArgs: gatsby.SourceNodesArgs,
) => {
  const { actions, createNodeId, createContentDigest } = gatsbyArgs
  const { createNode } = actions

  const nodeHelpers = createNodeHelpers({
    typePrefix: 'MyPlugin',
    createNodeId,
    createContentDigest,
  })

  const ProductNode = nodeHelpers.createNodeFactory<MyProduct>('Product')

  const products = await getAllProducts()

  for (const product of products) {
    const node = await ProductNode(product)
    // `node` now contains all the fields required by `createNode`
    // (e.g., id, parent, children, internal.contentDigest, internal.type, etc.)

    createNode(node)
  }
}