json2csv

Converts JSON into CSV with column titles and proper line endings.
Can be used as a module and from the command line.

See the CHANGELOG for details about the latest release.

🚧 The documentation seen here is for the upcoming v6 which is a work in progress, see https://www.npmjs.com/package/json2csv for the documentation for the latest published version. See v5 branch for code for v5+.

Features

Fast and lightweight
Scalable to infinitely large datasets (using stream processing)
Support for standard JSON as well as NDJSON
Advanced data selection (automatic field discovery, underscore-like selectors, custom data getters, default values for missing fields, transforms, etc.)
Highly customizable (supportting custom quotation marks, delimiters, eol values, etc.)
Automatic escaping (preserving new lines, quotes, etc. in them)
Optional headers
Unicode encoding support
Pretty printing in table format to stdout

How to install

You can install json2csv as a dependency using NPM.
Requires Node v12 or higher.

# Global so it can be called from anywhere
$ npm install -g json2csv
# or as a dependency of a project
$ npm install json2csv --save

Also, if you are loading json2csv directly to the browser you can pull it directly from the CDN.

<script src="https://cdn.jsdelivr.net/npm/json2csv"></script>

By default, the above script will get the latest release of json2csv. You can also specify a specific version:

<script src="https://cdn.jsdelivr.net/npm/json2csv@4.2.1"></script>

Usage

Command Line Interface

json2csv can be called from the command line if installed globally (using the -g flag).

Usage: json2csv [options]

Options:
  -V, --version                       output the version number
  -i, --input <input>                 Path and name of the incoming json file. Defaults to stdin.
  -o, --output <output>               Path and name of the resulting csv file. Defaults to stdout.
  -c, --config <path>                 Specify a file with a valid JSON configuration.
  -n, --ndjson                        Treat the input as NewLine-Delimited JSON.
  -s, --no-streaming                  Process the whole JSON array in memory instead of doing it line by line.
  -f, --fields <fields>               List of fields to process. Defaults to field auto-detection.
  -v, --default-value <defaultValue>  Default value to use for missing fields.
  -q, --quote <quote>                 Character(s) to use as quote mark. Defaults to '"'.
  -Q, --escaped-quote <escapedQuote>  Character(s) to use as a escaped quote. Defaults to a double `quote`, '""'.
  -d, --delimiter <delimiter>         Character(s) to use as delimiter. Defaults to ','. (default: ",")
  -e, --eol <eol>                     Character(s) to use as End-of-Line for separating rows. Defaults to '\n'. (default: "\n")
  -E, --excel-strings                 Wraps string data to force Excel to interpret it as string even if it contains a number.
  -H, --no-header                     Disable the column name header.
  -a, --include-empty-rows            Includes empty rows in the resulting CSV output.
  -b, --with-bom                      Includes BOM character at the beginning of the CSV.
  -p, --pretty                        Print output as a pretty table. Use only when printing to console.
  --unwind [paths]                    Creates multiple rows from a single JSON document similar to MongoDB unwind.
  --unwind-blank                      When unwinding, blank out instead of repeating data. Defaults to false. (default: false)
  --flatten-objects                   Flatten nested objects. Defaults to false. (default: false)
  --flatten-arrays                    Flatten nested arrays. Defaults to false. (default: false)
  --flatten-separator <separator>     Flattened keys separator. Defaults to '.'. (default: ".")
  -h, --help                          output usage information

If no input -i is specified the result is expected from to the console standard input. If no output -o is specified the result is printed to the console standard output. If no fields -f or config -c are passed the fields of the first element are used since json2csv CLI process the items one at a time. You can use the --no-streaming flag to load the entire JSON in memory and get all the headers. However, keep in mind that this is slower and requires much more memory. Use -p to show the result as a table in the console.

Any option passed through the config file -c will be overriden if a specific flag is passed as well. For example, the fields option of the config will be overriden if the fields flag -f is used.

For more details, you can check some of our CLI usage examples or our test suite.

Javascript module

json2csv can also be use programatically from you javascript codebase.

The programatic APIs take a configuration object very similar to the CLI options. All APIs take the exact same options.

fields - Array of Objects/Strings. Defaults to toplevel JSON attributes. See example below.
ndjson - Boolean, indicates that the data is in NDJSON format. Only effective when using the streaming API and not in object mode.
transforms - Array of transforms. A transform is a function that receives a data recod and returns a transformed record. Transforms are executed in order before converting the data record into a CSV row. See bellow for more details.
formatters - Object where the each key is a Javascript data type and its associated value is a formatters for the given type. A formatter is a function that receives the raw js value of a given type and formats it as a valid CSV cell. Supported types are the types returned by typeof i.e. undefined, boolean, number, bigint, string, symbol, function and object.
defaultValue - Default value to use when missing data. Defaults to <empty> if not specified. (Overridden by fields[].default)
delimiter - String, delimiter of columns. Defaults to , if not specified.
eol - String, overrides the default OS line ending (i.e. \n on Unix and \r\n on Windows).
header - Boolean, determines whether or not CSV file will contain a title column. Defaults to true if not specified.
includeEmptyRows - Boolean, includes empty rows. Defaults to false.
withBOM - Boolean, with BOM character. Defaults to false.

Transforms

json2csv supports transforms. A transform is a function that receives a data record and returns a transformed record.

Custom transforms

function doNothing(item) {
  // apply tranformations or create new object
  return transformedItem;
}

or using ES6

const doNothing = (item) => {
  // apply tranformations or create new object
  return transformedItem;
};

For example, let's add a line counter to our CSV, capitalize the car field and change the price to be in Ks (1000s).

function addCounter() {
  let counter = 1;
  return (item) => ({
    counter: counter++,
    ...item,
    car: item.car.toUpperCase(),
    price: item.price / 1000,
  });
}

Then you can add addCounter() to the transforms array. The reason to wrap the actual transform in a factory function is so the counter always starts with one and you can reuse it. But it's not strictly necessary.

Built-in Transforms

There is a number of built-in transform provider by the library.

const {
  transforms: { unwind, flatten },
} = require('json2csv');

Unwind

The unwind transform deconstructs an array field from the input item to output a row for each element. It's similar to MongoDB's $unwind aggregation.

The transform needs to be instantiated and takes an options object as arguments containing:

paths - Array of Strings, list the paths to the fields to be unwound. It's mandatory and should not be empty.
blankOut - Boolean, unwind using blank values instead of repeating data. Defaults to false.

// Default
unwind({ paths: ['fieldToUnwind'] });

// Blanking out repeated data
unwind({ paths: ['fieldToUnwind'], blankOut: true });

Flatten

Flatten nested JavaScript objects into a single level object.

The transform needs to be instantiated and takes an options object as arguments containing:

objects - Boolean, whether to flatten JSON objects or not. Defaults to true.
arrays- Boolean, whether to flatten Arrays or not. Defaults to false.
separator - String, separator to use between nested JSON keys when flattening a field. Defaults to ..

// Default
flatten();

// Custom separator '__'
flatten({ separator: '_' });

// Flatten only arrays
flatten({ objects: false, arrays: true });

Formatters

json2csv supports formatters. A formatter is a function that receives the raw js value of a given type and formats it as a valid CSV cell. Supported types are the types returned by typeof i.e. undefined, boolean, number, bigint, string, symbol, function and object.

There is a special type of formatter that only applies to the CSV headers if they are present. This is the header formatter and by default it uses the string formatter.

Pay special attention to the string formatter since other formatters like the headers or object formatters, rely on the string formatter for the stringification.

Custom Formatters

function formatType(itemOfType) {
  // format object
  return formattedItem;
}

or using ES6

const formatType = (itemOfType) => {
  // apply tranformations or create new object
  return itemOfType;
};

For example, let's format functions as their name or 'unknown'.

const functionNameFormatter = (item) => item.name || 'unknown';

Then you can add { function: functionNameFormatter } to the formatters object.

A less trivial example would be to ensure that string cells never take more than 20 characters.

const stringFixedFormatter = (stringLength, ellipsis = '...') => (item) =>
  item.length <= stringLength
    ? item
    : `${item.slice(0, stringLength - ellipsis.length)}${ellipsis}`;

Then you can add { string: stringFixedFormatter(20) } to the formatters object. Or stringFixedFormatter(20, '') to not use the ellipsis and just clip the text. As with the sample transform in the previous section, the reason to wrap the actual formatter in a factory function is so it can be parameterized easily.

Keep in mind that the above example doesn't quote or escape the string which is problematic. A more realistic example could use our built-in string formatted to do the quoting and escaping like:

const { formatters: { string: defaultStringFormatter } } = require('json2csv');

const stringFixedFormatter = (stringLength, ellipsis = '...', stringFormatter = defaultStringFormatter()) => (item) => item.length <= stringLength ? item :  stringFormatter(`${item.slice(0, stringLength - ellipsis.length)}${ellipsis})`;

Built-in Formatters

There is a number of built-in formatters provider by the library.

const {
  formatters: {
    default: defaultFormatter,
    number: numberFormatter,
    string: stringFormatter,
    stringQuoteOnlyIfNecessary: stringQuoteOnlyIfNecessaryFormatter,
    stringExcel: stringExcelFormatter,
    symbol: symbolFormatter,
    object: objectFormatter,
  },
} = require('json2csv');

Default

This formatter just relies on standard JavaScript stringification. This is the default formatter for undefined, boolean, number and bigint elements.

It's not a factory but the formatter itself.

{
  undefined: defaultFormatter,
  boolean: defaultFormatter,
  number: defaultFormatter,
  bigint: defaultFormatter,
}