# gatsby-transformer-json

> Gatsby transformer plugin for JSON files

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

## Install

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

## 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 | 2 |
| Unpacked size | 46.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55943 |
| Author | Kyle Mathews |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby |
| Keywords | gatsby, gatsby-plugin, json |

## Links

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

## Dependencies (2)

- [bluebird](https://npm.io/package/bluebird.md) ^3.7.2
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M 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
- … 429 more at https://npm.io/package/gatsby-transformer-json/versions

## README

# gatsby-transformer-json

Parses raw JSON strings into JavaScript objects e.g. from JSON files. Supports
arrays of objects and single objects.

## Install

`npm install gatsby-transformer-json`

If you want to transform JSON files, 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-json`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `./src/data/`,
      },
    },
  ],
}
```

## Parsing algorithm

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

### Array of Objects

The algorithm for arrays is to convert each item in the array into a node.

So if your project has a `letters.json` with

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

Then the following three nodes would be created:

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

### Single Object

The algorithm for single JSON 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.json
        b.json
        c.json
```

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

```json
{ "value": "a" }
```

```json
{ "value": "b" }
```

```json
{ "value": "c" }
```

Then the following three nodes would be created:

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

## How to query

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
{
  allLettersJson {
    edges {
      node {
        value
      }
    }
  }
}
```

Which would return:

```javascript
{
  allLettersJson: {
    edges: [
      {
        node: {
          value: "a",
        },
      },
      {
        node: {
          value: "b",
        },
      },
      {
        node: {
          value: "c",
        },
      },
    ]
  }
}
```

## 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 json with a
simple query):

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

```graphql
{
  allJson {
    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
  json content
- `object`: a single object (either an item from an array or the whole json content)
- `isArray`: boolean, true if `object` is part of an array

```json
[
  {
    "level": "info",
    "message": "hurray"
  },
  {
    "level": "info",
    "message": "it works"
  },
  {
    "level": "warning",
    "message": "look out"
  }
]
```

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

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

## Examples

The [gatsbygram example site](https://github.com/gatsbyjs/gatsby/blob/master/examples/gatsbygram/gatsby-node.js) uses this plugin.

## Troubleshooting

If some fields are missing or you see the error on build:

> There are conflicting field types in your data. GraphQL schema will omit those fields.

It's probably because you have arrays of mixed values somewhere. For instance:

```json
{
  "stuff": [25, "bob"],
  "orEven": [
    [25, "bob"],
    [23, "joe"]
  ]
}
```

If you can rewrite your data with objects, you should be good to go:

```json
{
  "stuff": [{ "count": 25, "name": "bob" }],
  "orEven": [
    { "count": 25, "name": "bob" },
    { "count": 23, "name": "joe" }
  ]
}
```

Else, if your data doesn't have a consistent schema, like [TopoJSON files](https://en.wikipedia.org/wiki/GeoJSON#TopoJSON), or you can't rewrite it, consider placing the JSON file inside the [`static` folder](/docs/static-folder/#when-to-use-the-static-folder) and use the dynamic import syntax (`import('/static/myjson.json')`) within the `componentDidMount` lifecycle or the `useEffect` hook.

### `id` and `jsonId` key

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

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