{"id":10930,"library":"gatsby-transformer-javascript-frontmatter","title":"Gatsby Transformer JavaScript Frontmatter","description":"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.","status":"active","version":"5.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript","gatsby","gatsby-plugin","js"],"install":[{"cmd":"npm install gatsby-transformer-javascript-frontmatter","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-transformer-javascript-frontmatter","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-transformer-javascript-frontmatter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Gatsby framework, required for all Gatsby plugins.","package":"gatsby","optional":false},{"reason":"Provides the files for this transformer to process.","package":"gatsby-source-filesystem","optional":false}],"imports":[{"note":"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.","wrong":"import { transformer } from 'gatsby-transformer-javascript-frontmatter';","symbol":"\"gatsby-transformer-javascript-frontmatter\"","correct":"// in gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-source-filesystem`,\n      options: {\n        name: `pages`,\n        path: `${__dirname}/src/pages/`,\n      },\n    },\n    \"gatsby-transformer-javascript-frontmatter\",\n  ],\n};"},{"note":"This is the recommended modern ES module syntax for defining frontmatter in `.js`, `.jsx`, `.ts`, or `.tsx` files for the plugin to process.","wrong":"export default { frontmatter: { title: \"My Page Title\" } };","symbol":"frontmatter (Named ES Export)","correct":"export const frontmatter = {\n  title: \"My Page Title\",\n  date: \"2023-01-15\"\n};"},{"note":"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.","wrong":"module.exports = { title: \"Another Page\" };","symbol":"frontmatter (CommonJS Export)","correct":"exports.frontmatter = {\n  title: \"Another Page\",\n  category: \"development\"\n};"}],"quickstart":{"code":"module.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-source-filesystem`,\n      options: {\n        name: `pages`,\n        path: `${__dirname}/src/pages/`,\n      },\n    },\n    \"gatsby-transformer-javascript-frontmatter\",\n  ],\n}\n\n// Example content file: src/pages/my-post.js\nimport React from \"react\"\n\nexport const frontmatter = {\n  title: \"Choropleth on d3v4\",\n  written: \"2017-05-04\",\n  layoutType: \"post\",\n  path: \"choropleth-on-d3v4\",\n  category: \"data science\",\n  description: \"Things about the choropleth.\",\n}\n\nexport default function MyComponent() {\n  return <div>My Post Content</div>\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<5.0.0"},{"fix":"Ensure that `gatsby` and `gatsby-source-filesystem` are installed at version `^5.0.0` or higher in your project's `package.json`.","message":"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.","severity":"breaking","affected_versions":"<5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Always use `export const frontmatter = { ... }` or `exports.frontmatter = { ... }` to define your metadata in JavaScript files.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"WebpackError: GraphQL Error Field 'allJavascriptFrontmatter' doesn't exist on type 'Query'"},{"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`.","cause":"Missing peer dependency for Gatsby, which is required by this transformer plugin.","error":"Error: Cannot find module 'gatsby'"},{"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.","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.","error":"The 'frontmatter' field in your GraphQL query returns null or expected fields are missing."}],"ecosystem":"npm"}