json-flat-csv

A lightweight, dependency-free Node.js utility to flatten nested JSON objects and export them into clean, standard CSV format.

Features

• 🚀 Zero external dependencies — highly performant and lightweight.
• 📦 Automatic Flattening — recursively flattens deeply nested objects and arrays.
• 🔒 Safe CSV Escaping — automatically handles fields with commas, quotes, and newlines.
• 🛠️ Custom Separators — configure separators for nested fields (e.g. user_address instead of user.address).
• 📊 Dynamic Columns — dynamically collects headers from all objects, ensuring no data is lost even if objects have different schemas.

Installation

npm install json-flat-csv

Usage

const { jsonToCsv } = require('json-flat-csv');

const users = [
  {
    id: 1,
    name: 'Alice',
    address: {
      city: 'New York',
      zip: '10001'
    },
    hobbies: ['reading', 'gaming']
  },
  {
    id: 2,
    name: 'Bob "The Builder"',
    address: {
      city: 'London'
      // zip is missing here
    },
    hobbies: ['sports']
  }
];

const csv = jsonToCsv(users);
console.log(csv);

Output

id,name,address.city,address.zip,hobbies.0,hobbies.1
1,Alice,New York,10001,reading,gaming
2,"Bob ""The Builder""",London,,sports,

Options

jsonToCsv(data, options) accepts the following options:

| Option | Type | Default | Description | |---|---|---|---| | separator | string | '.' | Key separator for nesting (e.g., . makes address.city, _ makes address_city). | | delimiter | string | ',' | Field delimiter character (e.g., , for CSV, \t for TSV). |

// Example with custom options (TSV style, snake-case properties)
const tsv = jsonToCsv(users, {
  separator: '_',
  delimiter: '\t'
});

License

MIT