# gatsby-transformer-yaml

> Gatsby transformer plugin for yaml

Latest version **5.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-transformer-yaml
pnpm add gatsby-transformer-yaml
yarn add gatsby-transformer-yaml
bun add gatsby-transformer-yaml
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.16.0 |
| Published | 2026-01-26 |
| First published | 2017-04-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 3 |
| Unpacked size | 44.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55939 |
| Author | Kyle Mathews |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby |
| Keywords | gatsby, gatsby-plugin, yaml |

## Links

- npm: https://www.npmjs.com/package/gatsby-transformer-yaml
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-yaml#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-transformer-yaml

## Dependencies (3)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 5.16.0 (latest) — 2026-01-26
- 5.17.0-next.0 (next) — 2025-11-27
- 5.17.0-react19.1 (react19) — 2025-11-26
- 3.15.0 (latest-v3) — 2022-12-07
- 4.25.0 (latest-v4) — 2022-12-07
- 5.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 4.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 5.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 4.23.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14
- 4.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- 4.23.0-alpha-9689ff.25 (alpha-9689ff) — 2022-08-31
- 4.18.0-alpha-drupal-self-reference.18 (drupal-self-reference) — 2022-07-19
- 4.15.0-alpha-wp-image-cdn-auth.48 (wp-image-cdn-auth) — 2022-05-20
- 4.8.0-alpha-image-service.24 (image-service) — 2022-02-10
- 4.6.0-alpha-ts-jit.60 (alpha-ts-jit) — 2022-01-21
- … 425 more at https://npm.io/package/gatsby-transformer-yaml/versions

## README

# gatsby-transformer-yaml

Parses YAML files. Supports arrays of objects and single objects.

Supported extensions: `.yaml`, `.yml`

Both `.yaml` and `.yml` are treated in the same way. This document uses both of them interchangeably.

## Install

`npm install gatsby-transformer-yaml`

**Note:** You also need to have `gatsby-source-filesystem` installed and configured so it
points to your files.

## How to use

In your `gatsby-config.js`

```javascript
module.exports = {
  plugins: [
    `gatsby-transformer-yaml`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `./src/data/`,
      },
    },
  ],
}
```

Where the _source folder_ `./src/data/` contains the `.yaml` files.

## Parsing algorithm

You can choose to structure your data as arrays of objects in individual files
or as single objects spread across multiple files.

The _source folder_ can contain either the following:

- **Array of Objects**: Where each file represents a collection. (_you probably want this one_)
- **Single Object**: Where each _subfolder_ represents a collection; each file represents one "record".

### Array of Objects

The algorithm for YAML arrays is to convert each item in the array into a node.
The type of the node is based on the filename.

So if your project has a `letters.yaml` which looks like:

```yaml
- character: a
- character: b
- character: c
```

Then the following three nodes would be created.

```json
[
  {
    "character": "a"
  },
  {
    "character": "b"
  },
  {
    "character": "c"
  }
]
```

### Single Object

The algorithm for single YAML objects is to convert the object defined at the
root of the file into a node. The type of the node is based on the name of the
parent directory.

For example, let's say your project has a data layout like:

```text
data/
    letters/
        a.yml
        b.yml
        c.yml
```

Where each of `a.yml`, `b.yml` and `c.yml` look like:

```yaml
character: a
```

```yaml
character: b
```

```yaml
character: c
```

Then the following three nodes would be created.

```json
[
  {
    "character": "a"
  },
  {
    "character": "b"
  },
  {
    "character": "c"
  }
]
```

## How to query

You can query the nodes using GraphQL, like from the GraphiQL browser: `http://localhost:8000/___graphql`.

Regardless of whether you choose to structure your data in arrays of objects or
single objects, you'd be able to query your letters like:

```graphql
{
  allLettersYaml {
    edges {
      node {
        character
      }
    }
  }
}
```

Which would return:

```javascript
{
  allLettersYaml: {
    edges: [
      {
        node: {
          character: "a",
        },
      },
      {
        node: {
          character: "b",
        },
      },
      {
        node: {
          character: "c",
        },
      },
    ]
  }
}
```

Please do **note** that `allLettersYaml` **will not** show up if you do not have any `.yaml` files.

## Configuration options

**`typeName`** [string|function][optional]

The default naming convention documented above can be changed with
either a static string value (e.g. to be able to query all yaml with a
simple query):

```javascript
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-yaml`,
      options: {
        typeName: `Yaml`, // a fixed string
      },
    },
  ],
}
```

```graphql
{
  allYaml {
    edges {
      node {
        value
      }
    }
  }
}
```

or a function that receives the following arguments:

- `node`: the graphql node that is being processed, e.g. a File node with
  yaml content
- `object`: a single object (either an item from an array or the whole yaml content)
- `isArray`: boolean, true if `object` is part of an array

```yaml
- level: info
  message: hurray
- level: info
  message: it works
- level: warning
  message: look out
```

```javascript
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-yaml`,
      options: {
        typeName: ({ node, object, isArray }) => object.level,
      },
    },
  ],
}
```

```graphql
{
  allInfo {
    edges {
      node {
        message
      }
    }
  }
}
```

## Troubleshooting

### `id` and `yamlId` key

If your data contains an `id` key the transformer will automatically convert this key to `yamlId` as `id` is a reserved internal keyword for Gatsby.

---
_Source: https://npm.io/package/gatsby-transformer-yaml · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._