gatsby-node-helpers

Gatsby node helper functions to aid node creation. To be used when creating Gatsby source plugins.

Note: The following documentation is incomplete and will be written at a later time.

Status

Installation

npm install --save gatsby-node-helpers

Quick Guide

Import

Import the default module:

import createNodeHelpers from 'gatsby-node-helpers'

Create node helpers

Call createNodeHelpers with options.

import createNodeHelpers from 'gatsby-node-helpers'

const {
  createNodeFactory,
  generateNodeId,
  generateTypeName,
} = createNodeHelpers({
  typePrefix: `Shopify`,
})

Create a node factory

Call createNodeFactory with a type name.

import createNodeHelpers from 'gatsby-node-helpers'

const {
  createNodeFactory,
  generateNodeId,
  generateTypeName,
} = createNodeHelpers({
  typePrefix: `Shopify`,
})

export const ProductNode = createNodeFactory(`Product`)

Use the node factory in your gatsby-node.js

ProductNode accepts an object and returns a new object to be passed to Gatsby's createNode action creator.

It handles setting up Gatsby's internal fields, including the content digest and node type.

// gatsby-node.js

import { ProductNode } from './nodes'
import { getAllProducts } from './api'

exports.sourceNodes = async ({ boundActionCreators }) => {
  const { createNode } = boundActionCreators

  const products = await getAllProducts()

  products.forEach(product => {
    const node = ProductNode(product)
    createNode(node)
  })
}

API

createNodeHelpers

Default export of the package.

({
  sourceId?: String,
  typePrefix: String,
  conflictFieldPrefix?: String
}) => ({
  createNodeFactory: (type: String, middleware?: Node => Node),
  generateNodeId: (type: String, id: String),
  generateTypeName: (type: String)
})

Inputs

The following options are provided as an object.

• sourceId?: String - Optional (default: __SOURCE__)

  Default source parent ID. If not defined, the node is set as a top-level node.

• typePrefix: String - Required

  Prefix for all nodes. Used a namespace for node type names and IDs. Must be PascalCase.

• conflictFieldPrefix?: String - Optional (default: camelcased typePrefix)

  Prefix for all fields conflicting with Gatsby's internal fields:

  • id
  • children
  • parent
  • fields
  • internal

Outputs

The following outputs are provided as an object.

• createNodeFactory: (type: String, middleware?: Node => Node)

  Jump to documentation: createNodeFactory

• generateNodeId: (type: String, id: String)

  Jump to documentation: generateNodeId

• generateTypeName: (type: String)

  Jump to documentation: generateTypeName

The following functions are generated by createNodeHelpers.

createNodeFactory

Creates a factory function that takes in an object and outputs a Gatsby createNode compatible object.

By default, the input object is kept intact, with the following exceptions:

• Fields conflicting with Gatsby's internal fields are prefixed.
• obj.id is set to a generated string containing typePrefix set in createNodeHelpers, type set in the factory function, and obj.id
• obj.parent is set to sourceId set in createNodeHelpers (__SOURCE__ by default)
• obj.children is set to [] by default
• obj.internal.type is set to a generated string containing typePrefix set in createNodeHelpers and type set in the factory function
• obj.internal.contentDigest is set to the MD5 hash of the object including Gatsby's internal fields.

A middleware function can be provided to modify the node beyond these exceptions. This can be used, for example, to set obj.children. The middleware function is passed the modified object and must return a Gatsby-comptabible object.

The resulting function of createNodeFactory can take in an object and an overrides object. This can be used, for example, to set obj.parent. The overrides object is merged with the modified object using Object.assign; no mutations are performed, so be careful with what you set.

generateNodeId

Creates a function that takes in a node type and node ID and returns a formatted string. It is used internally to create a node's ID, but it can be useful when setting obj.parent and obj.children in a middleware function or overrides object.

generateTypeName

Creates a function that takes in a node type and returns a formatted string. It is used internally to create a node's type name.

Type signature

(options: {
  sourceId?: String,
  typePrefix: String,
  conflictFieldPrefix?: String
  }) => {
  createNodeFactory: (type: String, middleware: )
}