Gatsby Transformer JavaScript Frontmatter

Common errors

• WebpackError: GraphQL Error Field 'allJavascriptFrontmatter' doesn't exist on type 'Query'

  cause The `gatsby-transformer-javascript-frontmatter` plugin or `gatsby-source-filesystem` is not correctly configured in `gatsby-config.js`, or `gatsby-source-filesystem` is not pointing to directories containing JavaScript files with `frontmatter` exports.
  fix Verify that `gatsby-transformer-javascript-frontmatter` is listed in your `plugins` array in `gatsby-config.js` and that `gatsby-source-filesystem` is configured to include the paths to your JavaScript/TypeScript files.

• Error: Cannot find module 'gatsby'

  cause Missing peer dependency for Gatsby, which is required by this transformer plugin.
  fix Install `gatsby` and `gatsby-source-filesystem` at version `^5.0.0` or higher: `npm install gatsby gatsby-source-filesystem` or `yarn add gatsby gatsby-source-filesystem`.

• The 'frontmatter' field in your GraphQL query returns null or expected fields are missing.

  cause The frontmatter was not correctly parsed, possibly due to incorrect export syntax in the source file or dynamic content that could not be statically analyzed.
  fix Check the source JavaScript/TypeScript file to ensure `export const frontmatter = { ... }` or `exports.frontmatter = { ... }` is used and that the content is statically analyzable. The GraphQL query also exposes an `error` field you can query to get detailed parsing errors.

Warnings

• breaking Gatsby v5 and this plugin require Node.js version 18.0.0 or higher. Using older Node.js versions (e.g., Node 16) will lead to build failures or runtime errors. Ensure your development environment and deployment targets meet the Node.js requirements specified in the package's `engines` field.
  Fix: Upgrade your Node.js environment to a supported version (e.g., Node.js 18 LTS, 20 LTS, or 22 LTS). Refer to Gatsby's official documentation for the latest Node.js compatibility matrix.
• breaking This transformer plugin is part of the Gatsby v5 ecosystem. It requires peer dependencies `gatsby` and `gatsby-source-filesystem` to be at least version `5.0.0`. Installing it with Gatsby v4 or earlier will result in dependency resolution issues and functional breakage.
  Fix: Ensure that `gatsby` and `gatsby-source-filesystem` are installed at version `^5.0.0` or higher in your project's `package.json`.
• gotcha The plugin relies on static analysis of JavaScript/TypeScript files using Babel. Dynamically generated `frontmatter` exports, or those involving complex runtime logic, may not be correctly parsed or extracted by the transformer.
  Fix: Ensure that your `exports.frontmatter` or `export const frontmatter` objects are statically analyzable, containing only primitive values or simple object/array literals. Avoid complex function calls or runtime calculations within the frontmatter definition itself.
• gotcha The plugin specifically looks for an export named `frontmatter`. Using `export default { title: '...' }` or `module.exports = { title: '...' }` will prevent the frontmatter from being detected and queried via GraphQL.
  Fix: Always use `export const frontmatter = { ... }` or `exports.frontmatter = { ... }` to define your metadata in JavaScript files.

Install

• npm install gatsby-transformer-javascript-frontmatter npm
• yarn add gatsby-transformer-javascript-frontmatter yarn
• pnpm add gatsby-transformer-javascript-frontmatter pnpm

Imports

• "gatsby-transformer-javascript-frontmatter"
  wrong:

  import { transformer } from 'gatsby-transformer-javascript-frontmatter';

  correct:

  // in gatsby-config.js
  module.exports = {
    plugins: [
      {
        resolve: `gatsby-source-filesystem`,
        options: {
          name: `pages`,
          path: `${__dirname}/src/pages/`,
        },
      },
      "gatsby-transformer-javascript-frontmatter",
    ],
  };

  Gatsby plugins are configured using their string name in `gatsby-config.js` and do not expose direct JavaScript symbols for import into user-land component code.
• frontmatter (Named ES Export)
  wrong:

  export default { frontmatter: { title: "My Page Title" } };

  correct:

  export const frontmatter = {
    title: "My Page Title",
    date: "2023-01-15"
  };

  This is the recommended modern ES module syntax for defining frontmatter in `.js`, `.jsx`, `.ts`, or `.tsx` files for the plugin to process.
• frontmatter (CommonJS Export)
  wrong:

  module.exports = { title: "Another Page" };

  correct:

  exports.frontmatter = {
    title: "Another Page",
    category: "development"
  };

  This CommonJS style export is also supported for defining frontmatter, particularly in older Gatsby projects or files not using ES module syntax. The plugin looks for a property named `frontmatter` on the `exports` object.

Quickstart

This quickstart demonstrates how to configure `gatsby-transformer-javascript-frontmatter` in `gatsby-config.js` alongside `gatsby-source-filesystem` and provides an example JavaScript file showing how to export frontmatter for the plugin to process.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `pages`,
        path: `${__dirname}/src/pages/`,
      },
    },
    "gatsby-transformer-javascript-frontmatter",
  ],
}

// Example content file: src/pages/my-post.js
import React from "react"

export const frontmatter = {
  title: "Choropleth on d3v4",
  written: "2017-05-04",
  layoutType: "post",
  path: "choropleth-on-d3v4",
  category: "data science",
  description: "Things about the choropleth.",
}

export default function MyComponent() {
  return <div>My Post Content</div>
}