export-to-csv | Export to CSV Mini Library

Like this library and want to support active development?

Small, simple, and single purpose. Zero dependencies, functionally inspired, and fairly well-typed.

If you're looking for a fully CSV-compliant, consistently maintained, whole-package library, I'd recommend looking elsewhere! (see alternatives section below)

If you want a lightweight, stable, easy-to-use basic CSV generation and download library, feel free to install.

Installation

1npm install --save export-to-csv

Usage

This library was written with TypeScript in mind, so the examples will be in TS.

You can easily use this library in JavaScript as well. The bundle uses ES modules, which all modern browsers support.

You can also look at the integration tests for browser/JS use, and the unit tests to understand how the library functions.

In-browser

1import { mkConfig, generateCsv, download } from "export-to-csv";
2
3// mkConfig merges your options with the defaults
4// and returns WithDefaults<ConfigOptions>
5const csvConfig = mkConfig({ useKeysAsHeaders: true });
6
7const mockData = [
8  {
9    name: "Rouky",
10    date: "2023-09-01",
11    percentage: 0.4,
12    quoted: '"Pickles"',
13  },
14  {
15    name: "Keiko",
16    date: "2023-09-01",
17    percentage: 0.9,
18    quoted: '"Cactus"',
19  },
20];
21
22// Converts your Array<Object> to a CsvOutput string based on the configs
23const csv = generateCsv(csvConfig)(mockData);
24
25// Get the button in your HTML
26const csvBtn = document.querySelector("#csv");
27
28// Add a click handler that will run the `download` function.
29// `download` takes `csvConfig` and the generated `CsvOutput`
30// from `generateCsv`.
31csvBtn.addEventListener("click", () => download(csvConfig)(csv));

Node.js

1import { mkConfig, generateCsv, asString } from "export-to-csv";
2import { writeFile } from "node:fs";
3import { Buffer } from "node:buffer";
4
5// mkConfig merges your options with the defaults
6// and returns WithDefaults<ConfigOptions>
7const csvConfig = mkConfig({ useKeysAsHeaders: true });
8
9const mockData = [
10  {
11    name: "Rouky",
12    date: "2023-09-01",
13    percentage: 0.4,
14    quoted: '"Pickles"',
15  },
16  {
17    name: "Keiko",
18    date: "2023-09-01",
19    percentage: 0.9,
20    quoted: '"Cactus"',
21  },
22];
23
24// Converts your Array<Object> to a CsvOutput string based on the configs
25const csv = generateCsv(csvConfig)(mockData);
26const filename = `${csvConfig.filename}.csv`;
27const csvBuffer = new Uint8Array(Buffer.from(asString(csv)));
28
29// Write the csv file to disk
30writeFile(filename, csvBuffer, (err) => {
31  if (err) throw err;
32  console.log("file saved: ", filename);
33});

Using generateCsv output as a string

Note: this is only applicable to projects using Typescript. If you're using this library with Javascript, you might not run into this issue.

There might be instances where you want to use the result from generateCsv as a string instead of a CsvOutput type. To do that, you can use asString, which is exported from this library.

1import { mkConfig, generateCsv, asString } from "export-to-csv";
2
3const csvConfig = mkConfig({ useKeysAsHeaders: true });
4
5const addNewLine = (s: string): string => s + "\n";
6
7const mockData = [
8  {
9    name: "Rouky",
10    date: "2023-09-01",
11    percentage: 0.4,
12    quoted: '"Pickles"',
13  },
14  {
15    name: "Keiko",
16    date: "2023-09-01",
17    percentage: 0.9,
18    quoted: '"Cactus"',
19  },
20];
21
22// Converts your Array<Object> to a CsvOutput string based on the configs
23const csvOutput = generateCsv(csvConfig)(mockData);
24
25// This would result in a type error
26// const csvOutputWithNewLine = addNewLine(csvOutput);
27// ❌ => CsvOutput is not assignable to type string.
28
29// This unpacks CsvOutput which turns it into a string before use
30const csvOutputWithNewLine = addNewLine(asString(csvOutput));

The reason the CsvOutput type exists is to prevent accidentally passing in a string which wasn't formatted by generateCsv to the download function.

Using generateCsv output as a Blob

A case for this would be using browser extension download methods instead of the supplied download function. There may be scenarios where using a Blob might be more ergonomic.

1import { mkConfig, generateCsv, asBlob } from "export-to-csv";
2
3// mkConfig merges your options with the defaults
4// and returns WithDefaults<ConfigOptions>
5const csvConfig = mkConfig({ useKeysAsHeaders: true });
6
7const mockData = [
8  {
9    name: "Rouky",
10    date: "2023-09-01",
11    percentage: 0.4,
12    quoted: '"Pickles"',
13  },
14  {
15    name: "Keiko",
16    date: "2023-09-01",
17    percentage: 0.9,
18    quoted: '"Cactus"',
19  },
20];
21
22// Converts your Array<Object> to a CsvOutput string based on the configs
23const csv = generateCsv(csvConfig)(mockData);
24
25// Generate the Blob from the CsvOutput
26const blob = asBlob(csvConfig)(csv);
27
28// Requires URL to be available (web workers or client scripts only)
29const url = URL.createObjectURL(blob);
30
31// Assuming there's a button with an id of csv in the DOM
32const csvBtn = document.querySelector("#csv");
33
34csvBtn.addEventListener("click", () => {
35  // Use Chrome's downloads API for extensions
36  chrome.downloads.download({
37    url,
38    body: csv,
39    filename: "chrome-extension-output.csv",
40  });
41});

API

Option	Default	Type	Description
fieldSeparator	","	string	Defines the field separator character
filename	"generated"	string	Sets the name of the file created from the download function
quoteStrings	false	boolean	Determines whether or not to quote strings (using quoteCharacter's value). Whether or not this is set, \r, \n, and fieldSeparator will be quoted.
quoteCharacter	'"'	string	Sets the quote character to use.
decimalSeparator	"."	string	Defines the decimal separator character (default is .). If set to "locale", it uses the language-sensitive representation of the number.
showTitle	false	boolean	Sets whether or not to add the value of title to the start of the CSV. (This is not supported by all CSV readers)
title	"My Generated Report"	string	The title to display as the first line of the CSV file. (This is not the name of the file [see filename])
showColumnHeaders	true	boolean	Determines if columns should have headers. When set to false, the first row of the CSV will be data.
columnHeaders	[]	Array<string | {key: string, displayLabel: string}>	Use this option if column/header order is important! Determines the headers to use as the first line of the CSV data. If the item is a string, it will be used for lookup in your collection AND as the header label. If the item is an object, key will be used for lookup, and displayLabel will be used as the header label.
useKeysAsHeaders	false	boolean	If set, the CSV will use the key names in your collection as headers. Warning: headers recommended for large collections. If set, it'll override the headers option. Column/header order also not guaranteed. Use headers only if order is important!
boolDisplay	{true: "TRUE", false: "FALSE"}	{true: string, false: string}	Determines how to display boolean values in the CSV. This only works for true and false. 1 and 0 will not be coerced and will display as 1 and 0.
useBom	true	boolean	Adds a byte order mark which is required by Excel to display CSVs, despite it not being necessary with UTF-8 🤷‍♂️
useTextFile	false	boolean	Deprecation warning. This will be removed in the next major version. Will download the file as text/plain instead of text/csv and use a .txt vs .csv file extension.
fileExtension	csv	string	File extension to use. Currently, this only applies if useTextFile is false.

Alternatives

As mentioned above, this library is intentionally small and was designed to solve a very simple need. It was not originally designed to be fully CSV compliant, so many things you need might be missing. I'm also not the most active on it (~7 year gap between updates). So, here are some alternatives with more support and that might be more fully featured.

• https://csv.js.org/
• https://www.papaparse.com/

Thanks!

This library was originally based on this library by Javier Telio

Credits and Original Authors
javiertelioz
sn123
arf1980