FAQ

Why do I get "Cannot find module" or "ERR_MODULE_NOT_FOUND"?

Always include the .js extension when importing stream-json modules:

// ✅ Correct
import {parser} from 'stream-json/parser.js';
import {pick} from 'stream-json/filters/pick.js';

// ❌ Wrong — will fail with Node.js ESM resolution
import {parser} from 'stream-json/parser';
import {pick} from 'stream-json/filters/Pick';

Node.js does not automatically resolve file extensions for packages that use subpath exports. The stream-json package uses "./*": "./src/*" in its exports field, so the full path including .js is required.

How do I use stream-json with ESM import?

stream-json 3.x is ESM-only ("type": "module") — import is the native and only supported way to load it. Use the .js extension in all import paths:

import {parser} from 'stream-json/parser.js';
import chain from 'stream-chain';

import pick from 'stream-json/filters/pick.js';
import replace from 'stream-json/filters/replace.js';
import ignore from 'stream-json/filters/ignore.js';
import filter from 'stream-json/filters/filter.js';

import streamValues from 'stream-json/streamers/stream-values.js';
import streamArray from 'stream-json/streamers/stream-array.js';
import streamObject from 'stream-json/streamers/stream-object.js';

import stringer from 'stream-json/stringer.js';
import emitter from 'stream-json/emitter.js';
import Assembler from 'stream-json/assembler.js';
import disassembler from 'stream-json/disassembler.js';

import batch from 'stream-json/utils/batch.js';
import verifier from 'stream-json/utils/verifier.js';
import emit from 'stream-json/utils/emit.js';

import jsonlParser from 'stream-json/jsonl/parser.js';
import jsonlStringer from 'stream-json/jsonl/stringer.js';

Every module exports its factory both as the default export and under its own name (the default-export + named-mirror convention), so either import style works:

// default import — the module itself is the factory
import pick from 'stream-json/filters/pick.js';
chain([source, parser(), pick({filter: 'data'}), streamValues()]);

// named import — destructure the named export
import {pick} from 'stream-json/filters/pick.js';
chain([source, parser(), pick({filter: 'data'}), streamValues()]);

How do I parse a large JSON array?

The most common use case: read a huge JSON file containing an array of objects and process each one with minimal memory.

import fs from 'node:fs';
import chain from 'stream-chain';
import streamArray from 'stream-json/streamers/stream-array.js';

const pipeline = chain([fs.createReadStream('large-file.json'), streamArray.withParser()]);

pipeline.on('data', ({key, value}) => {
  // key is the array index, value is the parsed object
  console.log(key, value);
});

pipeline.on('end', () => console.log('done'));

streamArray.withParser() combines a JSON parser with StreamArray in one step. Each array element is emitted as {key, value} without keeping the whole array in memory.

For async/await, Node.js streams are async-iterable:

const pipeline = chain([fs.createReadStream('large-file.json'), streamArray.withParser()]);

for await (const {key, value} of pipeline) {
  console.log(key, value);
}

See Recipe: streaming basics for more shapes (objects, JSONL) and tips.

How can I improve performance?

There is a special document for that: Performance.