Neoanthropic Preternatural Murmurings


Need private packages and team management tools?Check out npm Orgs. »


1.10.3 • Public • Published

node-jq logo

node-jq is a Node.js wrapper for jq - a lightweight and flexible command-line JSON processor


$ npm install node-jq --save
# or 
$ yarn add node-jq

Advanced installation

By default, node-jq downloads jq on the installation process (when you run npm install node-jq). Downloads the binaries according to your SO.

After that to run jq directly. Like: ./node_modules/node-jq/bin/jq . package.json.

If you want to skip the installation of jq, set NODE_JQ_SKIP_INSTALL_BINARY to 'true' like:

$ npm install node-jq


jq example

Usually in your CLI using jq:

$ jq ".abilities[].moves" bulbasaur.json

and you get


node-jq equivalent

With node-jq you could run it programmatically and interact with the output as a JavaScript Object:

NOTE: Take care of the filter that you are using with jq, mapping an array or any other iterative output isn't a valid JavaScript Object, that might fail at parse-time.

const jq = require('node-jq')
const filter = '.abilities[].moves'
const jsonPath = '/path/to/bulbasaur.json'
const options = {}, jsonPath, options)
  .then((output) => {
        "name": "heartgold-soulsilver",
        "power": "10"
        "name": "platinum",
        "power": "50"
        "name": "diamond-pearl",
        "power": "99"
  .catch((err) => {
    // Something went wrong...


path to jq binary

By default, the jq binary installed with the package is used. If you have special needs or want to use another binary in a different path you can set the environment variable JQ_PATH to override the default behaviour.


Description Type Values Default
Type of input string 'file', 'json', 'string' 'file'

input: 'file'

Run the jq query against a JSON file.'.', '/path/to/file.json').then(console.log)
// { "foo": "bar" }

input: 'file'

Run jq query against multiple JSON files.'.', ['/path/to/file.json','path/to/other_file.json']).then(console.log)
// { "foo": "bar" }
// { "otherFoo": "andBar" }

input: 'json'

Run the jq query against an Object.'.', { foo: 'bar' }, { input: 'json' }).then(console.log)
// { "foo": "bar" }

input: 'string'

Run the jq query against a String.'.', '{ foo: "bar" }', { input: 'string' }).then(console.log)
// { "foo": "bar" }


Description Values Default
Type of output 'pretty', 'json', 'compact', 'string' 'pretty'

output: 'pretty'

Return the output as a String.'.', '/path/to/file.json', { output: 'string' }).then(console.log)
// {
//   "foo": "bar"
// }

output: 'json'

Return the output as an Object.'.', '/path/to/file.json', { output: 'json' }).then(console.log)
// { foo: 'bar' }

output: 'compact'|'string'

Return the output as a String.'.', '/path/to/file.json', { output: 'compact' }).then(console.log)
// {"foo":"bar"}'.', '/path/to/file.json', { output: 'string' }).then(console.log)
// {"foo":"bar"}


Description Values Default
Read input stream into array true, false false

slurp: true

Read input stream into array.'.', ['/path/to/file.json','/path/to/other_file.json'], { output: 'json', slurp: true }).then(console.log)
// [
//   {
//     "foo": "bar"
//   },
//   {
//     "otherFoo": "andBar"
//   }
// ]


Description Values Default
Sort object keys in alphabetical order true, false false

sort: true

Sorts object keys alphabetically.'.', ['/path/to/file.json'], { output: 'json', sort: true }).then(console.log)
// {
//   "a": 2,
//   "b": 1
// },

Projects using node-jq


Why would you want to manipulate JavaScript Objects with jq inside a nodejs app, when there are tools like ramda or lodash?

The idea was to port jq in node to be able to run it as-is. node-jq doesn't try to replace Array/Object filters, maps, transformations, and so on.

Our primary goal was to make jq syntax available inside an Atom extension: atom-jq.

Other than that, jq is an interesting CLI tool to quickly parse and manipulate the response of an API, such as:

curl '' | jq '.[].postId'

There are also people dealing with complex use-cases, and some of them want to port their bash scripts to node:

Want to learn jq?

Seems hard to learn, but it really isn't.

jq is like sed for JSON. Slice, filter, map and transform structured data in a simple and powerful way.

Take a look at this great introduction or a jq lesson.

You can check out the official manual and fiddle around in the online playground





npm i node-jq

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability