How to Read CSV Files With Node.js

CSV is already one of the simplest data formats, but Node.js makes it even easier to work with.

CSV files are a convenient data-storage format, and you can use them in your Node.js projects to handle anything from configuration to raw data. They can simplify the sharing of information between two apps, even if they’re written in different languages.

In Node.js, you can use several methods to read and write CSV files.

This tutorial shows you how to use the fs module and fast-csv NPM package to read and write CSV files.

Project Setup

To follow along with this tutorial, ensure you have Node.js installed on your machine. Run this command to check:

node -v

It should return a version number. If you don’t have Node.js installed, follow the instruction in this installation tutorial to do so.

In your preferred directory, create a new folder named parse-csv.

mkdir parse-csv

Navigate to parse-csv and create a new file. Name it parseCSV.js.

cd parse-csv
touch parseCSV.js

You can now start working with CSV.

Using the fs Module

The fs (short for file system) module contains several commands for interacting with the file system in Node.js.

Read the Whole File at Once

The readFile() and readFileSync() commands from the fs module enable you to read file content in Node.js. The difference between these commands is that readFileSync() is synchronous—it blocks other JavaScript from executing—while readFile() is asynchronous, or non-blocking.

Since reading CSV files can take a bit of time, especially for large files, it's often better to use the non-blocking command, readFile(), as shown below.

const fs = require('fs');

fs.readFile('csvdemo.csv', 'utf8', function (err, data) {
    /* parse data */
});

If you don't have a sample CSV file, you can generate one from mockaroo. You can also learn how to create a CSV file yourself.

Read Line by Line

While readFile() works, it is memory intensive as it reads the whole CSV file all at once. This is a problem, especially when working with large CSV files. An alternative is to read one line at a time using the fs.createReadStream() command.

const fs = require("fs");
const readline = require("readline");
const stream = fs.createReadStream("./csvdemo.csv");
const rl = readline.createInterface({ input: stream });
let data = [];

rl.on("line", (row) => {
    data.push(row.split(","));
});

rl.on("close", () => {
    console.log(data);
});

Here, you are passing the CSV filename to fs.createReadStream() to create a readable stream. Streams let you work with large amounts of data by allowing you to access it in chunks.

Once you create the readable stream, pass it to readline.createInterface() method. The readline module provides an interface for reading the data one line at a time. You can now push each row to the data array as it’s being read.

Note, however, that this code simply splits each row on commas. Although this will work with the most basic CSV file, the format is actually more complicated than its name implies. Parsing CSV files manually is not a robust approach, especially if you are not in control of the data yourself. For most situations, you should use a CSV library.

Using fast-csv

To parse CSV files reliably, you can use a library like fast-csv, which is available as an npm package. It makes it easier to not only read CSV files but also format them.

To get started, initialize npm and install fast-csv.

npm init -y
npm i fast-csv

Read CSV files using fast-csv as follows.

const fs = require('fs')
const csv = require('fast-csv');
const data = []

fs.createReadStream('./csvdemo.csv')
  .pipe(csv.parse({ headers: true }))
  .on('error', error => console.error(error))
  .on('data', row => data.push(row))
  .on('end', () => console.log(data));

In the above code, start by creating a readable stream from the CSV file then connect it to the parse method from fast CSV using pipe(). Note that you are passing the headers option to csv.parse(). This skips the first row. Set headers to false if the first row of your CSV file does not contain headers.

As the CSV file is read one row at a time, you are pushing each row to the data array. After the whole file is read, you can manipulate the contents of the data array as you want.

There’s More Than One Way to Parse a CSV

CSV files are useful for storing large data sets because it’s easy to parse them. In Node.js, you can use the built-in fs module or NPM packages.

Using a library like fast-csv is much easier, and more robust, than writing your own parsing code manually. Some other packages for parsing CSV are csv-parser and papa parser.