{"id":15114,"library":"gatsby-node-helpers","title":"Gatsby Node Helpers","description":"The `gatsby-node-helpers` package provides a set of utility functions specifically designed to simplify and streamline the process of creating Gatsby nodes within source plugins. Its current stable version is 1.2.1. While not adhering to a strict time-based release cadence, the project actively publishes updates, with recent releases addressing feature enhancements and minor adjustments. It differentiates itself by abstracting away the complexities of Gatsby's internal node requirements, such as automatically generating `contentDigest`, handling Gatsby's reserved field conflicts through intelligent namespacing, and providing compliant functions for generating type names and unique IDs. This significantly streamlines the development of Gatsby source plugins by ensuring created nodes adhere to Gatsby's internal data model, reducing boilerplate and common errors associated with manual node creation in `gatsby-node.js` files.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/angeloashmore/gatsby-node-helpers","tags":["javascript","gatsby","gatsby-plugin","typescript"],"install":[{"cmd":"npm install gatsby-node-helpers","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-node-helpers","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-node-helpers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, the library enhances Gatsby's node creation API.","package":"gatsby","optional":false}],"imports":[{"note":"This is the primary factory function to initialize the helpers. It's intended for ESM usage in `gatsby-node.ts` or `gatsby-node.js`.","wrong":"const { createNodeHelpers } = require('gatsby-node-helpers')","symbol":"createNodeHelpers","correct":"import { createNodeHelpers } from 'gatsby-node-helpers'"},{"note":"createNodeFactory is a method returned by an instance of `createNodeHelpers`, not a direct export from the package.","wrong":"import { createNodeFactory } from 'gatsby-node-helpers'","symbol":"createNodeFactory","correct":"const ProductNode = nodeHelpers.createNodeFactory('Product')"},{"note":"This is a TypeScript type definition for the object returned by `createNodeHelpers` for better type inference and safety.","wrong":"import { GatsbyNodeHelpers } from 'gatsby-node-helpers'","symbol":"GatsbyNodeHelpers","correct":"import type { GatsbyNodeHelpers } from 'gatsby-node-helpers'"}],"quickstart":{"code":"import * as gatsby from 'gatsby'\nimport { createNodeHelpers } from 'gatsby-node-helpers'\n\ninterface MyProduct {\n  id: string;\n  name: string;\n  price: number;\n}\n\n// Simulate fetching product data\nasync function getAllProducts(): Promise<MyProduct[]> {\n  return [\n    { id: 'p1', name: 'Product A', price: 29.99 },\n    { id: 'p2', name: 'Product B', price: 49.99 }\n  ]\n}\n\nexport const sourceNodes: gatsby.GatsbyNode['sourceNodes'] = async (\n  gatsbyArgs: gatsby.SourceNodesArgs,\n) => {\n  const { actions, createNodeId, createContentDigest } = gatsbyArgs\n  const { createNode } = actions\n\n  const nodeHelpers = createNodeHelpers({\n    typePrefix: 'MyPlugin',\n    createNodeId,\n    createContentDigest,\n  })\n\n  const ProductNode = nodeHelpers.createNodeFactory<MyProduct>('Product')\n\n  const products = await getAllProducts()\n\n  for (const product of products) {\n    const node = await ProductNode(product)\n    // `node` now contains all the fields required by `createNode`\n    // (e.g., id, parent, children, internal.contentDigest, internal.type, etc.)\n\n    createNode(node)\n  }\n}","lang":"typescript","description":"Demonstrates initializing `createNodeHelpers` and using `createNodeFactory` to prepare product data for Gatsby's `createNode` action within the `sourceNodes` API."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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)`.","message":"When using `createNodeFactory` with an async middleware function, ensure you `await` the result of the factory call before passing it to `createNode`.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Always pass `gatsbyArgs.createNodeId` and `gatsbyArgs.createContentDigest` when initializing `createNodeHelpers`. Example: `createNodeHelpers({ typePrefix: 'MyPrefix', createNodeId, createContentDigest })`.","message":"The `createNodeHelpers` function requires Gatsby's `createNodeId` and `createContentDigest` functions from the `gatsbyArgs` object passed to Gatsby's Node APIs (like `sourceNodes`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `const { actions } = gatsbyArgs; const { createNode } = actions;` or directly `gatsbyArgs.actions.createNode(node)`.","cause":"`createNode` was not properly destructured from `actions` in Gatsby's Node APIs.","error":"TypeError: createNode is not a function"},{"fix":"Use `import { createNodeHelpers } from 'gatsby-node-helpers'` at the top of your `gatsby-node.js` or `gatsby-node.ts` file.","cause":"`createNodeHelpers` was not imported or was imported incorrectly (e.g., CommonJS `require` in an ESM context).","error":"ReferenceError: createNodeHelpers is not defined"},{"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`).","cause":"Missing or incorrect Gatsby TypeScript types, or an outdated Gatsby version not matching the type definitions.","error":"Cannot find name 'GatsbyNode' / Property 'sourceNodes' does not exist on type 'GatsbyNode'"}],"ecosystem":"npm"}