Nefarious Planetary Meddling

    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • 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 during the installation process with a post-install script. Depending on your SO downloads from [] into ./node_modules/node-jq/bin/jq to avoid colisions with any global installation. Check #161 #167 #171 for more information. You can safely rely on this location for your installed jq, we won't change this path without a major version upgrade.

    If you want to skip the installation step of jq, you can set NODE_JQ_SKIP_INSTALL_BINARY to true or ignore the post-install script from the installation npm install node-jq --ignore-scripts.

    npm install node-jq
    npm install node-jq --ignore-scripts


    jq example

    Usually in your CLI using jq:

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

    and you get

      "name": "heartgold-soulsilver",
      "power": "10"
      "name": "platinum",
      "power": "50"
      "name": "diamond-pearl",
      "power": "99"

    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 binary path.


    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' with multiple files

    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






    Unpacked Size

    84.6 kB

    Total Files


    Last publish


    • mackermans-admin
    • davesnx