Registry / web-framework / gatsby-transformer-javascript-frontmatter

gatsby-transformer-javascript-frontmatter

library5.16.0jsnpmunverified

This is a Gatsby transformer plugin designed to extract metadata, commonly known as "frontmatter," directly from JavaScript, TypeScript, JSX, or TSX files within a Gatsby project. It operates by statically analyzing `exports.frontmatter` or `export const frontmatter` declarations using `@babel/parser` and `@babel/traverse`. The current stable version, `5.16.0`, aligns with the Gatsby v5 ecosystem. Its release cadence is tied to the main Gatsby monorepo, receiving updates alongside Gatsby core to ensure compatibility with new Node.js versions (e.g., Node.js 24 support in `5.16.0`) and address security vulnerabilities. Its key differentiator is enabling developers to define content metadata directly within their component or data files using standard JavaScript exports, providing a unified location for code and content configuration, distinct from traditional Markdown-based frontmatter solutions.

web-framework data

npm install gatsby-transformer-javascript-frontmatter

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-TRANSFORMER

gatsby-transformer-javascript-frontmatter

web-frameworkjavascriptv5.16.0

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.

"gatsby-transformer-javascript-frontmatter"

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

✗ import { transformer } from '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)

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

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

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)

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

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

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.

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

Debug

Known issues

breakingGatsby 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.

affects: <5.0.0

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

affects: <5.0.0

gotchaThe 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.

affects: >=5.0.0

gotchaThe 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.

affects: >=5.0.0

Errors

Common errors & fixes

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

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'

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.

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.

Upgrade

Version history

5.16.0latest on npm

Audit

Dependencies

gatsbyrequiredCore Gatsby framework, required for all Gatsby plugins.

gatsby-source-filesystemrequiredProvides the files for this transformer to process.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/gatsby-transformer-javascript-frontmatter ↗