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

const PRODUCT_TYPE = `Product`
const PRODUCT_VARIANT_TYPE = `ProductVariant`

export const ProductNode = createNodeFactory(PRODUCT_TYPE, node => {
  if (node.variants) {
    const variants = node.variants.edges.map(edge => edge.node)

    // Set additional fields
    const variantPrices = variants
      .map(variant => Number.parseFloat(variant.price))
      .filter(Boolean)
    node.minPrice = Math.min(...variantPrices) || 0
    node.maxPrice = Math.max(...variantPrices) || 0

    // Set children
    node.children = variants.map(variant =>
      generateNodeId(PRODUCT_VARIANT_TYPE, variant.id),
    )

    // Remove unnecessary fields
    delete node.variants
  }

  return node
})

export const ProductVariantNode = createNodeFactory(PRODUCT_VARIANT_TYPE)

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 productNode = ProductNode(product)
    createNode(productNode)

    product.variants.edges.forEach(edge => {
      const variant = edge.node
      const productVariantNode = ProductVariantNode(variant, {
        parent: productNode.id,
      })
      createNode(productVariantNode)
    })
  })
}

API

createNodeHelpers

Default export of the package.

({
  sourceId?: String,
  typePrefix: String,
  conflictFieldPrefix?: String
}) => ({
  createNodeFactory: (type: String, middleware?: Node => Node) => (obj: Object, overrides?: Object),
  generateNodeId: (type: String, id: String) => String,
  generateTypeName: (type: String) => 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) => (obj: Object, overrides?: Object)

Jump to documentation: createNodeFactory

generateNodeId: (type: String, id: String) => String

Jump to documentation: generateNodeId

generateTypeName: (type: String) => String

Jump to documentation: generateTypeName

The following functions are generated by createNodeHelpers.

createNodeFactory

;(type: String, middleware?: Node => Node) => (
  obj: Object,
  overrides?: Object,
) => Node

Inputs

type: String - Required

The type of the node the resulting function will create.

middleware?: Node => Node - Optional (default: identity function)

Allows for modifying the node beyond the default Gatsby fields. This function recieves the Node object and must return the Node object, with modifications if necessary.

The middleware function is called at the following point:

1. Clone the input object and add Gatsby internal fields.
2. HERE =>: Run Node through middleware, modifiying fields as necessary.
3. Merge node with overrides provided to createNodeFactory's resulting function.

Typical uses of the middleware function is setting up the children field, adding new fields based on the object, and removing unecessary fields.

Outputs

(obj: Object, overrides?: Object) => Node

Factory function to create a Gatsby createNode compatible object.

It takes in an object, sets it up for Gatsby using the previously defined options (see Inputs above), merges any overrides provided, and returns an object.

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

The overrides parameter allows for a final chance to override any node field. The object is merged directly with no modifications.

generateNodeId

;(type: String, id: String) => String

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.

Because it is used internally to create a node's ID, it can be useful when setting obj.parent and obj.children in a middleware function or overrides object. The result will always be the same as long as the same type and ID are provided.

Inputs

type: String - Required

Type of the node.

id: String - Required

ID of the node. Must be unique scoped to the type.

Outputs

String

A formatted string containing typePrefix, type and id. Used internally to consistently generate node IDs.

generateTypeName

(type: String): String

Inputs

type: String - Required

Type of the node.

Outputs

String

A formatted string containing typePrefix and type. Used internally to consistently generate node type names.