Registry / web-framework / gatsby-node-helpers

gatsby-node-helpers

library1.2.1jsnpmunverified

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.

web-framework

npm install gatsby-node-helpers

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-NODE-HELPER

gatsby-node-helpers

web-frameworkjavascriptv1.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createNodeHelpers

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

✗ const { createNodeHelpers } = require('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

✓ const ProductNode = nodeHelpers.createNodeFactory('Product')

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

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

GatsbyNodeHelpers

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

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

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

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

Debug

Known issues

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

affects: >=0.2.0

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

affects: >=0.3.0

gotchaThe `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 })`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: createNode is not a function

`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

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

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

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency, the library enhances Gatsby's node creation API.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/angeloashmore/gatsby-node-helpers ↗

packagehttps://www.npmjs.com/package/gatsby-node-helpers ↗