Official Plugin

gatsby-transformer-csv

Parses CSV files into JSON arrays.

Install

npm install gatsby-transformer-csv

Note: You generally will use this plugin together with the gatsby-source-filesystem plugin. gatsby-source-filesystem reads in the files then this plugin transforms the files into data you can query.

How to use

If you put your .csv files in ./src/data:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `data`,
        path: `${__dirname}/src/data/`,
      },
    },
    `gatsby-transformer-csv`,
  ],
}

Configuration

The example above is the minimal configuration required to begin working. Additional customization of the parsing process is possible using the parameters listed in csvtojson. Any parameter listed on that page can be passed directly to the library using the plugin options.

For example, to pass the noheader option, you can configure like so:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `data`,
        path: `${__dirname}/src/data/`,
      },
    },
    {
      resolve: `gatsby-transformer-csv`,
      options: {
        noheader: true,
      },
    },
  ];
}

By default, files that do not have a .csv extension will not be parsed, but this can be configured using the extensions option which takes an array of strings.

For example, if you need to parse TSV files, you can configure the plugin like so:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `data`,
        path: `${__dirname}/src/data/`,
      },
    },
    {
      resolve: `gatsby-transformer-csv`,
      options: {
        extensions: [`tsv`],
        delimiter: '\t'
      },
    },
  ];
}

You can see an example project at https://github.com/gatsbyjs/gatsby/tree/master/examples/using-csv.

Parsing algorithm

By default each row is converted into a node with CSV headers as the keys.

If your project has a letters.csv with:

letter,value
a,65
b,66
c,67

The following three nodes would be created:

[
  { "letter": "a", "value": 65, "type": "LettersCsv" },
  { "letter": "b", "value": 66, "type": "LettersCsv" },
  { "letter": "c", "value": 67, "type": "LettersCsv" }
]

Alternatively the typeName plugin option can be used to modify this behaviour.

Its arguments are either a string denoting the type name or a function that accepts an argument object of { node, object } which should return the string type name.

Two predefined functions are provided.

const { typeNameFromDir, typeNameFromFile } = require("gatsby-transformer-csv")

typeNameFromFile will produce a type per CSV file. When the typeName plugin option is undefined, this is the default case. A file name of letters.csv will produce a type of LettersCsv.

typeNameFromDir will produce a type per folder of CSVs. A folder called things containing CSVs will return a type of ThingsCsv.

As an example of a custom function, if the CSVs are in a group of folders, and you wish to create a group per folder with the suffix “Data”. In this case a folder called things containing CSVs will return a type of ThingsData.

// In your gatsby-config.js
const _ = require(`lodash`)
const path = require(`path`)

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-csv`,
      options: {
        typeName: ({ node, object }) =>
          _.upperFirst(_.camelCase(`${path.basename(node.dir)} Data`)),
      },
    },
  ],
}

The suffix Csv is not added when providing your own function.

If you wanted to have a group per folder with the suffix “Csv”, the typeNameFromDir provided function would be appropriate.

// In your gatsby-config.js
const { typeNameFromDir } = require("gatsby-transformer-csv")

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-csv`,
      options: {
        typeName: typeNameFromDir,
      },
    },
  ],
}

Alternate content behaviour

The nodePerFile plugin option can either be false, which creates a node per line like above, true, which creates a node per file, with the key items containing the content, or a string which is the key containing the content.

For example, if there are a series of csv files called vegetables.csv, grains.csv, the following config would produce the following result.

The config:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-csv`,
      options: {
        typeName: () => `Foodstuffs`,
        nodePerFile: `ingredients`,
      },
    },
  ],
}

A query:

{
  allFoodstuffs {
    nodes {
      ingredients {
        ingredient
        amount
      }
      parent {
        ... on File {
          name
        }
      }
    }
  }
}

The result:

{
  "data": {
    "allFoodstuffs": {
      "nodes": [
        {
          "parent": {
            "name": "vegetables"
          },
          "ingredients": [
            {
              "ingredient": "potato",
              "amount": 32
            },
            {
              "ingredient": "lettuce",
              "amount": 12
            }
          ]
        },
        {
          "parent": {
            "name": "grains"
          },
          "ingredients": [
            {
              "ingredient": "barley",
              "amount": 2
            },
            {
              "ingredient": "wheat",
              "amount": 42
            }
          ]
        }
      ]
    }
  }
}

How to query

In the default configuration, items can be queried like this:

{
  allLettersCsv {
    edges {
      node {
        letter
        value
      }
    }
  }
}

Which would return:

{
  "allLettersCsv": {
    "edges": [
      {
        "node": {
          "letter": "a",
          "value": 65
        }
      },
      {
        "node": {
          "letter": "b",
          "value": 66
        }
      },
      {
        "node": {
          "letter": "c",
          "value": 67
        }
      }
    ]
  }
}