npm csv to json: A practical Node.js CSV-to-JSON guide

Learn how to convert CSV files to JSON in Node.js using npm packages like csv-parser or csvtojson. This practical guide covers streaming, CLI usage, and data quality tips.

MyDataTables Team

March 22, 2026·5 min read

MyDataTables CSV with JSON Read CSV CSV Parser

CSV to JSON with npm - MyDataTables — Photo by hitesh choudhary via Pexels

Quick AnswerDefinition

This guide demonstrates npm csv to json workflows using popular npm packages such as csv-parser or csvtojson. You read the CSV via a readable stream, transform rows into JSON objects, and write or emit the resulting array or stream. For small files you can load the entire dataset into memory; for large files, streaming keeps memory usage predictable. Code-first steps follow.

Understanding the npm csv to json landscape

Converting CSV to JSON with Node.js is a frequent data engineering task. With npm packages like csv-parser (streaming) or csvtojson (CLI and parser), you can parse headers, coerce values, and shape output for APIs or databases. The streaming approach shines for large files, as it avoids buffering the entire dataset in memory. In this primer, we compare a simple programmatic path against a quick CLI-based path. The MyDataTables team emphasizes writing clear, maintainable code and predictable memory behavior, so you can scale from tiny datasets to multi-GB files without surprises.

JavaScript

// Example: streaming CSV -> JSON using csv-parser
const fs = require('fs');
const csv = require('csv-parser');

const results = [];
fs.createReadStream('data/input.csv')
  .pipe(csv())
  .on('data', (row) => results.push(row))
  .on('end', () => {
    console.log(JSON.stringify(results, null, 2));
  });

The library emits each row as a plain object using headers as keys.
Streaming preserves small memory footprint and enables backpressure-aware pipelines.

Prerequisites for Node.js CSV parsing

Before diving into npm csv to json workflows, ensure your environment is ready. You’ll need a recent Node.js runtime, npm for package management, and a sample CSV file to test with. This section provides version hints and a minimal project setup so your environment is predictable across machines. As the MyDataTables analysis notes, reproducible environments reduce debugging time and headaches in data tooling.

Bash

# Initialize a new Node project
npm init -y

# Install the CSV parser for CSV -> JSON conversion
npm install csv-parser

JavaScript

// package.json snippet for deterministic installs
{
  "name": "csv-to-json-tool",
  "version": "1.0.0",
  "dependencies": {
    "csv-parser": "^3.0.0"
  }
}

Basic conversion: a simple CSV to JSON script

Here is a minimal, working script that reads input.csv and prints JSON to stdout. This setup is ideal for quick tests and small projects. We’ll rely on csv-parser to convert each row into an object, accumulating results for output. It’s easy to adapt to custom headers and post-processing logic as your data evolves.

JavaScript

// convert.js
const fs = require('fs');
const csv = require('csv-parser');

const results = [];
fs.createReadStream('data/input.csv')
  .pipe(csv())
  .on('data', (row) => results.push(row))
  .on('end', () => {
    // pretty JSON to stdout
    console.log(JSON.stringify(results, null, 2));
  });

Bash

# Run the script and save output
node convert.js > data/output.json

What you get: a JSON array where each element corresponds to a CSV row, with keys derived from the header row. You can easily modify the script to write to a file or pipe to another process for downstream consumption.

Alternative: quick conversion with a CLI (csvtojson)

If you want a fast, script-free conversion, the CSV-to-JSON CLI is ideal. Install it globally and perform a direct CSV->JSON transformation from the terminal. This path is great for one-off tasks or ad-hoc data pipelines that don’t require a full Node script.

Bash

# Install a CLI-friendly CSV-to-JSON tool
npm install -g csvtojson

# Convert input.csv to output.json directly
csvtojson data/input.csv > data/output.json

Notes

The CLI uses headers as JSON keys, producing a straightforward array of objects by default.
For very large CSVs, consider streaming options or producing NDJSON for incremental processing.

Handling large CSVs: streaming and JSONL output

Large CSV files demand streaming approaches to keep memory usage bounded. A compact pattern is to emit one JSON object per line (NDJSON) so downstream systems can process data incrementally. This section demonstrates streaming the parsed rows directly to a JSONL file, avoiding the need to hold the entire dataset in memory.

JavaScript

// ndjson-stream.js
const fs = require('fs');
const csv = require('csv-parser');
const out = fs.createWriteStream('data/output.ndjson');

fs.createReadStream('data/input.csv')
  .pipe(csv())
  .on('data', (row) => {
    out.write(JSON.stringify(row) + '\n');
  })
  .on('end', () => {
    out.end();
    console.log('NDJSON written to data/output.ndjson');
  });

Bash

node ndjson-stream.js

Why NDJSON? It enables downstream processing in streaming pipelines, dashboards, or data lakes without buffering the entire dataset in memory, and many tools accept line-delimited JSON as a simple data interchange format.

Encoding, BOM handling, and header quirks

CSV files can carry BOM markers and various encodings, which may lead to garbled data or mismatched headers if not handled carefully. This section demonstrates a robust, encoding-aware approach using a small helper for clean headers and a library to normalize UTF-8 inputs. Handling encoding up front improves reliability across data sources and locales.

Bash

npm install iconv-lite

JavaScript

// bom-safe read with header normalization
const fs = require('fs');
const csv = require('csv-parser');
const iconv = require('iconv-lite');

const results = [];
fs.createReadStream('data/input.csv')
  .pipe(iconv.decodeStream('utf8'))
  .pipe(csv({ mapHeaders: ({ header }) => header.trim() }))
  .on('data', (row) => results.push(row))
  .on('end', () => console.log(JSON.stringify(results, null, 2)));

Takeaways

Normalize headers (trim and consistent casing) to prevent downstream failures.
Ensure all inputs are consistently encoded (UTF-8 is a solid default).

Validation and shaping after conversion

Raw JSON output may need validation and shaping to meet downstream schema requirements. This section demonstrates using Ajv to validate an array of objects against a simple schema, and to report errors for remediation. Data validation helps catch structural issues before persistence or API calls.

Bash

npm install ajv

JavaScript

// validate.js
const Ajv = require('ajv');
const fs = require('fs');
const data = require('./data/output.json');

const ajv = new Ajv();
const schema = {
  type: 'array',
  items: {
    type: 'object',
    additionalProperties: true
  }
};

const valid = ajv.validate(schema, data);
console.log('Valid:', valid);
if (!valid) {
  console.log('Errors:', ajv.errors);
}

What to do with invalid data

Log and quarantine bad records during a pipeline pass, then fix headers or types in a follow-up pass.
Add a dedicated normalization step (e.g., numeric coercion) before persisting.

Real-world end-to-end workflow: normalize and persist

A robust CSV-to-JSON workflow in production involves reading, validating, transforming, and persisting data. This example shows an end-to-end script that normalizes numeric fields and dates, then writes to a JSON file suitable for ingestion by a database or API. You can adapt the mapping logic to your schema, add error handling, and integrate with a larger ETL pipeline.

JavaScript

// end-to-end: input.csv -> output.json with field normalization
const fs = require('fs');
const csv = require('csv-parser');

function toNumber(v) {
  const n = Number(v);
  return isNaN(n) ? null : n;
}

const results = [];
fs.createReadStream('data/input.csv')
  .pipe(csv())
  .on('data', (row) => {
    const normalized = {
      id: row['id'],
      name: row['name'],
      count: toNumber(row['count']),
      date: new Date(row['date']).toISOString()
    };
    results.push(normalized);
  })
  .on('end', () => {
    fs.writeFileSync('data/output.json', JSON.stringify(results, null, 2));
    console.log('Wrote', results.length, 'records to output.json');
  });

Bash

node end-to-end.js

Notes

Ensure the input CSV has headers id,name,count,date and adapt the normalization to your data types and time zones.
For large datasets, consider streaming and incremental persistence to a database for resilience.

Steps

Estimated time: 30-60 minutes

1
Create project directory
Set up a new folder for your CSV-to-JSON tooling and initialize a Node project with npm init -y.
Tip: Keep a dedicated folder to avoid mixing with other scripts.
2
Install dependencies
Install csv-parser (and optionally other parsers) to handle CSV parsing.
Tip: Lock versions to ensure reproducibility.
3
Prepare input CSV
Place your sample input.csv in the data/ folder with headers matching your expected output fields.
Tip: Validate headers before parsing.
4
Create conversion script
Write a Node.js script (convert.js) that streams CSV data and builds a JSON array or writes NDJSON.
Tip: Prefer streaming for large files.
5
Run and test
Execute the script and inspect data/output.json to verify correctness.
Tip: Use a json pretty-printer to review output.
6
Extend with validation
Add a schema validation step using Ajv to enforce data quality before persisting.
Tip: Treat validation as a first-class step in your pipeline.

Pro Tip: Prefer streaming parses for large CSVs to avoid high memory usage.

Warning: Watch out for BOM and encoding issues; ensure UTF-8 input.

Note: When naming fields, prefer stable keys that won't change across cohorts.

Pro Tip: Use JSON Lines (NDJSON) if downstream systems prefer streaming input.

Prerequisites

Required

Node.js 14.x or higher↗
Required
npm 6.x or higher
Required
A sample CSV file to convert
Required
Basic command line knowledge
Required

Optional

Optional: csv-parser or csvtojson packages↗
Optional

Commands

Action	Command
Install csv-parser for Node.js CSV parsingRun in your project directory	`npm install csv-parser`
Convert CSV to JSON using a scriptInput: data/input.csv; Output: data/output.json	`node convert.js`
Install csvtojson CLI for quick conversionsGlobal install for CLI usage	`npm install -g csvtojson`
Convert CSV to JSON with csvtojsonAdjust paths as needed	`csvtojson data/input.csv > data/output.json`

Main Points

Choose a streaming approach for large CSVs
Use csv-parser for robust Node.js parsing
Validate and shape JSON before persisting
CSV-to-JSON workflows scale with streaming and proper encoding

← More in CSV Tools & Apps

npm csv to json: A practical Node.js CSV-to-JSON guide

Understanding the npm csv to json landscape

Prerequisites for Node.js CSV parsing

Basic conversion: a simple CSV to JSON script

Alternative: quick conversion with a CLI (csvtojson)

Handling large CSVs: streaming and JSONL output

Encoding, BOM handling, and header quirks

Validation and shaping after conversion

Real-world end-to-end workflow: normalize and persist

Steps

Create project directory

Install dependencies

Prepare input CSV

Create conversion script

Run and test

Extend with validation

Prerequisites

Commands

People Also Ask

Main Points

Related Articles