Public API

Papa.parse

Papa.parse(
  input: string | File | NodeJS.ReadableStream,
  config?: {
    delimiter?: string;
    newline?: string;
    quoteChar?: string;
    escapeChar?: string;
    header?: boolean;
    dynamicTyping?: boolean;
    preview?: number;
    encoding?: string;
    worker?: boolean;        // browser only
    comments?: boolean | string;
    step?: (results: ParseResult, parser: Parser) => void;
    complete?: (results: ParseResult, file?: File) => void;
    error?: (error: ParseError, file?: File) => void;
    download?: boolean;      // browser only
    skipEmptyLines?: boolean | 'greedy';
    chunk?: (results: ParseResult, parser: Parser) => void;
    fastMode?: boolean;
    transform?: (value: string, field: string | number) => any;
    transformHeader?: (header: string, index?: number) => string;
  }
): ParseResult | void;

Use Papa.parse to convert a CSV string, local File object, or Node.js Readable stream into structured data. Pass a step callback for streaming large files row-by-row without loading the entire dataset into memory. Pass complete for a one-shot result when the full file is small enough to hold in memory.

Papa.unparse

Papa.unparse(
  data: object[] | any[][] | { fields: string[]; data: any[][] },
  config?: {
    quotes?: boolean | boolean[];
    quoteChar?: string;
    escapeChar?: string;
    delimiter?: string;
    header?: boolean;
    newline?: string;
    skipEmptyLines?: boolean | 'greedy';
    columns?: string[];
  }
): string;

Use Papa.unparse to serialize an array of objects or a 2-D array back into a CSV string. Accepts an optional config to control delimiters, quoting behavior, and which columns to include. Returns the resulting CSV as a plain string ready to write to disk or send in an HTTP response.

Papa.NODE_STREAM_INPUT

Papa.NODE_STREAM_INPUT: symbol;

A sentinel value passed as the first argument to Papa.parse when you want Node.js pipe-style streaming. When this symbol is the input, Papa.parse returns a writable stream you can pipe a Readable into. Use the data event on the returned stream to process rows and the end event to finalize. The step, complete, and worker config options are unavailable in this mode.

Working examples

Scenario - Parse a CSV string synchronously

Parsing a small in-memory CSV string and receiving the full result object. Suitable for unit tests or small data transformations.

import Papa from 'papaparse';

const csv = `name,age,active
Alice,30,true
Bob,25,false`;

const result = Papa.parse(csv, {
  header: true,
  dynamicTyping: true,
  skipEmptyLines: true,
});

console.log(result.data);
// [ { name: 'Alice', age: 30, active: true }, { name: 'Bob', age: 25, active: false } ]
console.log(result.errors); // []

Scenario - Stream a large CSV file in Node.js

Reading a multi-gigabyte CSV from disk using Node.js streams so memory usage stays flat. Each row is processed individually via the step callback.

import Papa from 'papaparse';
import fs from 'fs';

const file = fs.createReadStream('./data/large.csv');

Papa.parse(file, {
  header: true,
  dynamicTyping: true,
  skipEmptyLines: true,
  step(row) {
    // process one parsed row at a time
    console.log(row.data);
  },
  complete() {
    console.log('Parsing complete');
  },
  error(err) {
    console.error('Parse error:', err.message);
  },
});

Scenario - Pipe a stream with NODE_STREAM_INPUT

Using the Node.js pipe API for idiomatic stream chaining, collecting parsed rows via the data event.

import Papa from 'papaparse';
import fs from 'fs';

const readStream = fs.createReadStream('./data/records.csv');

const parseStream = Papa.parse(Papa.NODE_STREAM_INPUT, {
  header: true,
  dynamicTyping: true,
});

const rows: object[] = [];

parseStream.on('data', (row: object) => {
  rows.push(row);
});

parseStream.on('end', () => {
  console.log(`Parsed ${rows.length} rows`);
});

readStream.pipe(parseStream);

Scenario - Serialize JSON to CSV

Converting an array of objects to a CSV string and writing it to disk.

import Papa from 'papaparse';
import fs from 'fs';

const data = [
  { id: 1, product: 'Widget', price: 9.99 },
  { id: 2, product: 'Gadget', price: 24.50 },
];

const csv = Papa.unparse(data, {
  header: true,
  delimiter: ',',
});

fs.writeFileSync('./output/products.csv', csv, 'utf-8');
console.log(csv);
// id,product,price
// 1,Widget,9.99
// 2,Gadget,24.5

File walkthrough

• papaparse.js - The authoritative UMD source file; supports AMD, CommonJS (Node.js), and browser globals. This is the file that gets executed when you import or require the package.
• papaparse.min.js - Minified version of the same source for browser <script> tag inclusion; do not use this in Node.js builds.
• package.json - Declares main: "papaparse.js" and the npm metadata; no runtime dependencies listed.
• Gruntfile.js - Build tooling to regenerate the minified file and run the test suite; not needed at runtime.
• docs/ - Complete static website for papaparse.com; irrelevant to library integration but useful for offline documentation reference.
• player/ - A self-contained CSV visualization demo; not part of the library API.
• .github/workflows/node.js.yml - CI configuration running tests on pull requests; ignore for integration purposes.
• bower.json - Legacy Bower manifest; npm is the preferred package manager.
• .eslintrc.js - Code style rules used during development; copy or ignore as needed.

Common pitfalls and fixes

• worker: true crashes in Node.js - The worker option spawns a Blob-based Web Worker and requires a browser environment; always omit worker in Node.js code.
• ESM/CJS interop with default export - PapaParse exports a CommonJS default; in ESM with "type": "module" use import Papa from 'papaparse' (not a named import), or add "esModuleInterop": true in tsconfig.json.
• encoding option is Node-specific - When parsing a file stream in Node.js, encoding must be a Node-supported encoding (e.g., 'utf8', 'latin1'). Browser encoding labels (e.g., 'UTF-8') may not be accepted.
• step and complete are mutually exclusive with NODE_STREAM_INPUT - When using the pipe API, those callbacks are silently ignored; use stream data and end events instead.
• Empty lines producing empty row objects - When header: true and skipEmptyLines is not set, trailing newlines create {} entries; always set skipEmptyLines: true or skipEmptyLines: 'greedy'.
• dynamicTyping converts "true"/"false" strings to booleans - This is intentional but can be surprising; set dynamicTyping: false or use a custom transform function if you need raw strings.

Vibe-coding prompt template

I have a copy of the PapaParse CSV parser library (papaparse@5.5.3) in the
`source/` directory of this project, along with a `USAGE.md` integration guide.

Please read `USAGE.md` and `source/papaparse.js` carefully, then help me
integrate PapaParse into my existing project by doing the following step by step:

1. Install or alias the library so it can be imported as `papaparse`.
2. Create a utility module at `src/lib/csv.ts` that exports:
   - `parseCSV(input, options)` wrapping `Papa.parse`
   - `toCSV(data, options)` wrapping `Papa.unparse`
   - `streamCSV(readableStream, onRow, onDone)` using `Papa.NODE_STREAM_INPUT`
3. Add TypeScript types (use @types/papaparse if available).
4. Write at least one test for each exported function using the real PapaParse API.
5. Point out any ESM/CJS interop issues specific to my `tsconfig.json` and fix them.

Use only the APIs documented in `USAGE.md` and visible in `source/papaparse.js`.
Do not invent method names. Show complete file contents for every file you create or modify.

License and credit

PapaParse is released under the MIT License (see source/LICENSE). Upstream project: papaparse on npm / GitHub repository. Original author: Matt Holt (@mholt6).

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.