node-jq

library6.3.1jsnpmunverified

node-jq is a Node.js wrapper that allows developers to programmatically execute `jq`, the lightweight and flexible command-line JSON processor. It handles the installation of the `jq` binary by default during the `npm install` process, placing it within the package's `node_modules` directory to avoid global conflicts. Users can also configure it to use an existing `jq` binary via environment variables or `.npmrc`. The package currently stands at version 6.3.1 (as of late August 2025) and exhibits an active release cadence with frequent bug fixes and minor feature updates. Its primary differentiator is providing a simple, promise-based API to interact with `jq`'s powerful JSON querying capabilities directly within Node.js applications, abstracting away the complexities of child process management and binary execution. It ships with TypeScript types, facilitating modern development workflows.

serialization data

npm install node-jq

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-JQ

node-jq

serializationjavascriptv6.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jq (default export)

✓ import jq from 'node-jq';

✗ const jq = require('node-jq');

ESM import for modern Node.js environments. The package exports a default object which contains the `run` method and other utilities. Using `require()` for this syntax in an ESM module will lead to errors.

jq.run (method)

✓ import jq from 'node-jq'; // then use jq.run(filter, jsonPath, options)

✗ import { run } from 'node-jq'; // or const { run } = require('node-jq');

The `run` function is a method on the default `jq` export, not a named export itself. Attempting to destructure or named import `run` will fail.

jq (CommonJS)

✓ const jq = require('node-jq'); // then use jq.run(filter, jsonPath, options)

✗ import jq from 'node-jq';

CommonJS import for older Node.js environments or projects. This provides the default exported object containing the `run` method.

JqOptions (type)

✓ import type { JqOptions } from 'node-jq';

✗ import { JqOptions } from 'node-jq';

As a TypeScript type, it should be imported using `import type` to ensure it's removed during compilation and avoids potential runtime issues or bundle size increase.

This quickstart demonstrates how to use `node-jq` to process a local JSON file. It shows two examples: one extracting a list of ability names into a JavaScript array, and another constructing a new JavaScript object containing the Pokémon's name and an array of its move names. It includes setup for creating a temporary JSON file, error handling, and cleanup.

import jq from 'node-jq'; import { promises as fs } from 'node:fs'; import { fileURLToPath } from 'node:url'; import { dirname, resolve } from 'node:path'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); async function processPokemonData() { const bulbasaurData = { "id": 1, "name": "bulbasaur", "abilities": [ {"slot": 1, "is_hidden": false, "ability": {"name": "overgrow", "url": "https://pokeapi.co/api/v2/ability/65/"}}, {"slot": 3, "is_hidden": true, "ability": {"name": "chlorophyll", "url": "https://pokeapi.co/api/v2/ability/34/"}} ], "moves": [ {"move": {"name": "tackle", "url": "https://pokeapi.co/api/v2/move/33/"}, "version_group_details": []} ] }; const tempFilePath = resolve(__dirname, 'temp-bulbasaur.json'); await fs.writeFile(tempFilePath, JSON.stringify(bulbasaurData, null, 2)); // Filter to get an array of ability names const filterAbilityNames = '.abilities[].ability.name'; // Output will be an array of strings like: ["overgrow", "chlorophyll"] try { console.log('--- Extracting Ability Names ---'); const abilityNames = await jq.run(filterAbilityNames, tempFilePath, { input: 'file', output: 'json' }); console.log('Filtered ability names:', abilityNames); // Filter to create a new object with name and an array of move names const filterCustomObject = '{ name: .name, move_names: [.moves[].move.name] }'; // Output will be an object like: { "name": "bulbasaur", "move_names": ["tackle"] } console.log('\n--- Creating Custom Object with Move Names ---'); const customObject = await jq.run(filterCustomObject, tempFilePath, { input: 'file', output: 'json' }); console.log('Custom filtered object:', customObject); } catch (err) { console.error('Error processing JSON with node-jq:', err); } finally { await fs.unlink(tempFilePath).catch(() => {}); // Clean up temp file } } processPokemonData();

Debug

Known issues

gotchaBy default, `node-jq` installs the `jq` binary using a post-install script. If `npm install --ignore-scripts` (or `yarn add --ignore-scripts`, `pnpm install --ignore-scripts`) is used, the `jq` binary will not be installed, leading to runtime errors when `node-jq` attempts to execute `jq`.

fix

Ensure post-install scripts are enabled during installation. Alternatively, manually provide the `jq` binary path via the `JQ_PATH` environment variable or by configuring `jq-path` in your project's `.npmrc` file.

affects: >=1.0.0

gotchaWhen `node-jq`'s `run` method is used with `output: 'json'`, it expects the `jq` filter to produce valid JSON that can be parsed into a single JavaScript object or array. If the `jq` filter produces multiple, distinct JSON documents (e.g., `.` on an array of objects) or non-JSON output, `node-jq` will throw a `SyntaxError` during parsing.

fix

Craft `jq` filters carefully to ensure the output is a single, valid JSON document (e.g., wrap iterative outputs in an array like `[.[]]`). If processing multiple `jq` outputs as a stream is required, consider an alternative approach or process `node-jq`'s raw string output directly.

affects: >=1.0.0

gotchaThe `jq` binary location can be configured using the `JQ_PATH` environment variable or the `jq-path` setting in `.npmrc`. These configurations take precedence over the bundled `jq` binary. Incorrectly setting these paths can lead to `jq` not being found at runtime.

fix

Verify that `JQ_PATH` points to a valid `jq` executable or that `jq-path` in `.npmrc` is correctly configured and accessible in your environment. Remember that `JQ_PATH` overrides `.npmrc`.

affects: >=1.0.0

breakingThe package requires Node.js version 18 or higher as specified by its `engines` field. Running `node-jq` on older Node.js versions will result in runtime errors due to unsupported syntax or missing core APIs.

fix

Upgrade your Node.js environment to version 18 or newer to ensure compatibility and leverage modern JavaScript features.

affects: <18

Errors

Common errors & fixes

Error: Command failed: /path/to/node_modules/node-jq/bin/jq: Command not found

The `jq` binary was not found at the expected path. This typically occurs when installation scripts were skipped during `npm install` or if a custom `JQ_PATH` or `jq-path` in `.npmrc` points to an incorrect or non-existent location.

fix

Ensure that post-install scripts are enabled when installing `node-jq`. If using a custom path, verify that `JQ_PATH` environment variable or `jq-path` in `.npmrc` correctly specifies the absolute path to a functional `jq` executable.

SyntaxError: Unexpected token { in JSON at position X (or similar JSON parsing error from `JSON.parse`)

The `jq` filter produced output that `node-jq`'s `run` method (with `output: 'json'`) could not parse as a single, valid JSON entity. This often happens if the `jq` filter outputs multiple, distinct JSON objects without being wrapped in an array, or if the output is not valid JSON.

fix

Adjust your `jq` filter to always produce a single, well-formed JSON document. For example, to output an array of objects, use `[.[]]` at the end of your filter. If you need to process multiple individual JSON documents, retrieve the output as a string (`output: 'string'`) and parse it manually.

TypeError: jq.run is not a function

The `jq` object imported or required does not expose a `run` method, indicating an incorrect import pattern for `node-jq`.

fix

For ESM, ensure you use `import jq from 'node-jq';`. For CommonJS, use `const jq = require('node-jq');`. The `run` function is a method on the default export, not a named export or a standalone function.

Upgrade

Version history

6.3.1latest on npm

Audit

Dependencies

jqrequiredCore binary dependency. node-jq downloads and manages the jq binary by default, or can be configured to use a system-wide jq. The package will not function without a 'jq' executable.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/sanack/node-jq ↗

packagehttps://www.npmjs.com/package/node-jq ↗