Gatsby Transformer Plugins — Converting Raw Data to Usable Formats

In this tutorial, you will learn about Gatsby Transformer Plugins. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Gatsby transformer plugins for converting raw data nodes: Markdown to HTML, YAML to objects, and images to optimized formats.

In this lesson, you'll understand how transformer plugins work, how to configure them, and how they extend the GraphQL schema with transformed data.

What You'll Learn

How transformer plugins convert source data, how to use gatsby-transformer-remark, gatsby-transformer-yaml, gatsby-transformer-json, and gatsby-transformer-sharp.

Why It Matters

Source plugins create raw file nodes. Transformer plugins convert them into formats you can use in components — Markdown becomes HTML, images become responsive picture elements.

flowchart LR
    A[Raw File Node] --> B[Transformer Plugin]
    B --> C[Transformed Node]
    C --> D[Extra GraphQL Fields]
    C --> E[Queryable Content]
    style B fill:#639,color:#fff

gatsby-transformer-remark

Converts .md files to HTML-rich nodes:

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-source-filesystem',
    'gatsby-transformer-remark'
  ]
};

Query transformed Markdown:

query {
  allMarkdownRemark {
    nodes {
      html
      excerpt(pruneLength: 300)
      timeToRead
      wordCount { words }
      frontmatter {
        title
        date(formatString: "MMMM D, YYYY")
        tags
        featured
      }
    }
  }
}

Output: Each .md file becomes a MarkdownRemark node with html, excerpt, timeToRead, wordCount, and parsed frontmatter fields.

gatsby-transformer-yaml

Converts .yaml files to queryable objects:

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-source-filesystem',
    'gatsby-transformer-yaml'
  ]
};

# src/data/products.yaml
- id: 1
  name: Widget Pro
  price: 29.99
  category: widgets
  features:
    - Durable
    - Lightweight
    - Water-resistant

query {
  allProductsYaml {
    nodes {
      name
      price
      category
      features
    }
  }
}

Output: The YAML file becomes a ProductsYaml node type. Each top-level array entry becomes a node.

gatsby-transformer-json

Similar to YAML, but for JSON files:

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-source-filesystem',
    'gatsby-transformer-json'
  ]
};

[
  { "id": 1, "name": "About", "path": "/about" },
  { "id": 2, "name": "Contact", "path": "/contact" }
]

query {
  allNavigationJson {
    nodes { name path }
  }
}

Output: JSON files become queryable nodes. Useful for navigation menus, configuration, and static data.

gatsby-transformer-sharp

Processes images for optimized output:

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp'
  ]
};

This plugin adds childImageSharp to image File nodes:

query {
  file(relativePath: { eq: "photo.jpg" }) {
    childImageSharp {
      gatsbyImageData(
        width: 800
        placeholder: BLURRED
        formats: [AVIF, WEBP, AUTO]
      )
    }
  }
}

Output: The image file gets a childImageSharp field with optimized image data. This is the foundation of gatsby-plugin-image.

Custom Transformer Pipeline

Chain multiple transformers:

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-source-filesystem',
    'gatsby-transformer-remark',
    'gatsby-remark-images',   // Processes images in Markdown
    'gatsby-remark-prismjs',   // Syntax highlighting in code blocks
    'gatsby-remark-copy-linked-files'  // Copies linked files
  ]
};

// gatsby-config.js — remark plugins configuration
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-remark',
      options: {
        plugins: [
          {
            resolve: 'gatsby-remark-images',
            options: { maxWidth: 800 }
          },
          {
            resolve: 'gatsby-remark-prismjs',
            options: { classPrefix: 'language-' }
          }
        ]
      }
    }
  ]
};

Output: Markdown content gets processed through multiple remark plugins: images are optimized, code blocks get syntax highlighting, and linked files are copied to the build.

Common Mistakes

1. Installing transformer without the right source: gatsby-transformer-remark needs gatsby-source-filesystem to provide the Markdown files. The transformer works on the File nodes created by the source.
2. Not restarting after adding transformers: Transformer plugins in config require restarting the dev server to Process data.
3. Forgetting gatsby-plugin-sharp with gatsby-transformer-sharp: Both plugins are needed. gatsby-plugin-sharp provides Sharp utilities, gatsby-transformer-sharp adds childImageSharp to File nodes.
4. Using wrong YAML structure: YAML transformer expects either an array (each item becomes a node) or a keyed object. Nested structures may not map to nodes.
5. Not configuring remark sub-plugins: Sub-plugins like gatsby-remark-images are configured inside the gatsby-transformer-remark options, not at the top-level plugins array.

Practice Questions

1. What does a transformer plugin do? Answer: It converts raw data nodes (files) into transformed nodes with additional fields and functionality (e.g., Markdown to HTML, images to optimized formats).

2. How do you configure remark sub-plugins? Answer: Inside the gatsby-transformer-remark options, create a plugins array with the sub-plugin configurations.

3. What does gatsby-transformer-sharp add to File nodes? Answer: A childImageSharp field with image processing data (gatsbyImageData, fixed, fluid, original).

4. What happens if you forget gatsby-plugin-sharp? Answer: gatsby-transformer-sharp won't work because Sharp image processing utilities aren't available.

Challenge

Create a documentation site where each Markdown file includes images and code blocks. Configure gatsby-remark-images, gatsby-remark-prismjs, and gatsby-remark-copy-linked-files. Verify all features work.

Mini Project

Build a recipe site using YAML files with gatsby-transformer-yaml. Each recipe has ingredients, steps, prep time, and cook time. Create pages for each recipe and a listing page with filters.

FAQ

What's Next

Learn about Creating Pages Programmatically in Gatsby to generate pages from data at build time.