Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Source and Transformer Plugins

Transformer Plugins

Learn how Gatsby transformer plugins turn File nodes into content nodes: gatsby-transformer-remark, JSON, YAML, CSV and sharp, with parent and child node relationships.

A File node knows a file's name and size but not what is inside it. Transformer plugins bridge that gap. A transformer watches for nodes of a certain kind (for example Markdown files), reads their content, parses it and creates new nodes with structured data (the HTML, the front matter, the headings). Sources fetch; transformers interpret. Together they turn espresso.md into a queryable MarkdownRemark node.

All Gatsby code in this lesson is read-only. The stand-ins parse a mini Markdown file and build a parent/child node tree, so you can run and change every step.

How a transformer works

A transformer implements the onCreateNode API from gatsby-config and the Node APIs. Gatsby calls it for every new node. The plugin checks whether the node is one it understands, reads the content and creates a child node with createNode and createParentChildLink:

flowchart TD
  F["File node<br/>content/posts/espresso.md"] -->|"onCreateNode"| T["gatsby-transformer-remark"]
  T --> M["MarkdownRemark node<br/>(child of the File)"]
  M --> Q["Queried as<br/>markdownRemark and allMarkdownRemark"]

The child node keeps a link to its parent, so you can always find the original file.

The common transformers

Plugin Understands Creates
gatsby-transformer-remark .md, .markdown files MarkdownRemark
gatsby-plugin-mdx .mdx files Mdx (covered in the Markdown and MDX chapter)
gatsby-transformer-json .json files one node per object, typed by file name
gatsby-transformer-yaml .yaml, .yml one node per entry
gatsby-transformer-csv .csv one node per row
gatsby-transformer-sharp image File nodes ImageSharp

Transformers need a source that provides the files. Install them in the same plugins list; order does not matter between a source and its transformer, because Gatsby processes nodes as they appear, but both must be present.

JavaScript
// gatsby-config.js (real Gatsby, read-only)
module.exports = {
  plugins: [
    { resolve: "gatsby-source-filesystem", options: { name: "posts", path: `${__dirname}/content/posts` } },
    { resolve: "gatsby-source-filesystem", options: { name: "data", path: `${__dirname}/content/data` } },
    "gatsby-transformer-remark",
    "gatsby-transformer-json",
  ],
}

Markdown with gatsby-transformer-remark

A Markdown file with front matter:

MARKDOWN
---
title: "Espresso basics"
date: "2026-01-05"
tags: ["coffee", "brewing"]
---

Espresso is **concentrated** coffee made under pressure.

## Grind size

Finer than drip, coarser than Turkish.

After the transformer runs you can query it:

GRAPHQL
query {
  allMarkdownRemark {
    nodes {
      frontmatter { title date(formatString: "MMMM D, YYYY") tags }
      html
      excerpt(pruneLength: 120)
      timeToRead
      headings { value depth }
      tableOfContents
    }
  }
}
  • frontmatter is the YAML block, typed automatically (schema inference).
  • html is the rendered body.
  • excerpt, timeToRead, headings and tableOfContents are computed fields.

Remark has its own plugins (subplugins) for syntax highlighting, responsive images, external link attributes and more. They are listed under options.plugins of gatsby-transformer-remark and are covered in the Markdown chapter.

JSON and YAML data

gatsby-transformer-json creates nodes whose type comes from the file name (or the parent folder). A file content/data/authors.json:

JSON
[
  { "id": "ada", "name": "Ada Lovelace" },
  { "id": "alan", "name": "Alan Turing" }
]

becomes the types AuthorsJson (query with allAuthorsJson). Use the typeName option to choose another type name. This is a lightweight way to store settings, menus or small data sets without a CMS.

Parent and child relationships

Every transformed node knows its parent, and each parent lists its children. In queries you can traverse back with fields like parent { ... on File { relativePath } }. A transformer-created node is a child of the file: childMarkdownRemark on a File node gives the Markdown content.

GRAPHQL
query {
  allFile(filter: { sourceInstanceName: { eq: "posts" } }) {
    nodes {
      relativePath
      childMarkdownRemark { frontmatter { title } }
    }
  }
}

Stand-in: a tiny Markdown transformer

This stand-in is not gatsby-transformer-remark. It reacts to File nodes with a .md extension, parses front matter and converts headings and paragraphs into HTML, then links the new node to its parent.

JS Stand-in: transform a File node into a post node

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: a JSON transformer naming its type

JS Stand-in: type name from the file name

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Do not name a JSON property id unless you want it to become the node ID. If your JSON objects already have an id, make sure it is unique across the data layer, or rename it to avoid clashes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the job of a transformer plugin?

    Transformers read nodes created by sources and create structured child nodes.
  2. 2. Which API does a transformer implement?

    onCreateNode runs per node, so the transformer can react to the files it understands.
  3. 3. How is the type name for gatsby-transformer-json decided by default?

    authors.json becomes AuthorsJson, queried with allAuthorsJson.
  4. 4. How do you reach the Markdown content from a File node?

    Transformer nodes are children, exposed as childMarkdownRemark.

Summary

  • Sources create nodes; transformers interpret them and create child nodes.
  • gatsby-transformer-remark, JSON, YAML, CSV and sharp cover the common formats.
  • A transformer is an onCreateNode implementation that calls createNode and links parent and child.
  • Markdown nodes expose frontmatter, html, excerpt, headings and more.
  • JSON and YAML type names come from file names; keep IDs unique.

Next: Creating Nodes with sourceNodes