Skip to content
Easily encode complex JSON objects to CSV with CsvBuilder's schema-like API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Easily encode complex JSON objects to CSV with CsvBuilder's schema-like API.

Table Of Contents


const CsvBuilder = require('csv-builder')

const data = [
    name: 'Foo Bar',
    meta: {
      active: true,
      roles: [

const builder = new CsvBuilder({
  headers: ['Firstname', 'Lastname', 'Role 1', 'Role 2', 'Active'],
  alias: {
    'Role 1': 'meta.roles[0]',
    'Role 2': 'meta.roles[1]',
    'Active': ''
  .virtual('Firstname', user =>' ')[0])
  .virtual('Lastname', user =>' ')[1])

/* Each of the following produces the following CSV contents:

"Firstname","Lastname","Role 1","Role 2","Active"


// (1) Create from a Stream of objects (like a database)

// (2) Create from an existing payload (`data` is an array of objects)

// (3) Roll your own
let csv = ''
csv += builder.getHeaders()
data.forEach(item => {
  csv += builder.getRow(item)
fs.writeFileSync('output.csv', csv)


$ npm i -s csv-builder
# or
$ yarn add csv-builder

New Features

  • More cohesive API
  • Expanded API to support non-stream outputs, i.e. building a CSV string row-by-row with the getHeaders() and getRow(object) methods respectively.
  • Better CSV encoding (proper quoting by default)


  • headers String|Array Space separated headers, or array of headers (required)
  • delimiter String The column delimiter. Default ','
  • terminator String The row terminator. Default '\n'
  • quoted Boolean Quote columns? Default true
  • alias Object An object in the format of { "csv header": "object prop" }, object prop will be aliased to csv header. Default {}


CsvBuilder#createReadStream(payload): Stream.Readable

Creates a readable stream and consumes the payload.

  • payload Array<Object> Incoming data.
CsvBuilder#createTransformStream(): Stream.Transform

Creates a transform stream. The stream expects either Objects or JSON.

CsvBuilder#headers(headers): this
  • headers String|Array Space separated headers, or array of headers
CsvBuilder#alias(header, prop): this

Set single or multiple contraints. If header is an object, it will extend any existing constraints, not replace.

  • header String|Object Either object {"header": "property"} Or a string "Header"
  • prop String|undefined Property to correspond to header, omit if using object.
CsvBuilder#virtual(prop, fn): this

Create a virtual property. Virtual properties are treated the same as normal properties. If there is no corresponding header or alias, the virtual will not be present in resulting CSV.

  • prop String Virtual property name
  • fn (item: any) => any Where item is an element from the incoming data, and the return value is the corresponding value for the virtualized property.
CsvBuilder#getHeaders(): String

The headers in CSV format

CsvBuilder#getRow(item): String

Returns the CSV formated row for a given item.

  • item Object A n item matching the "schema".

Migration to 1.0.0

  • constraints attribute in options (for constructor) is deprecated, use alias instead.
  • set(prop, value) method is deprecated, use alias(prop, value) instead.
You can’t perform that action at this time.