# jq-web

> a hack that makes jq run in the browser with emscripten.

Latest version **0.6.2** (published 2025-03-19) · ISC license · 0 weekly downloads

## Install

```sh
npm install jq-web
pnpm add jq-web
yarn add jq-web
bun add jq-web
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.2 |
| Published | 2025-03-19 |
| First published | 2017-05-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 3.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 363 |
| Author | fiatjaf |
| Maintainers | fiatjaf |
| Keywords | emscriptem, jq, json, filter, path |

## Links

- npm: https://www.npmjs.com/package/jq-web
- Repository: https://github.com/fiatjaf/jq-web
- Homepage: https://github.com/fiatjaf/jq-web#readme
- Issues: https://github.com/fiatjaf/jq-web/issues
- npm.io page: https://npm.io/package/jq-web

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.6.2 (latest) — 2025-03-19
- 0.6.1 — 2025-02-13
- 0.6.0 — 2024-11-04
- 0.5.1 — 2019-11-03
- 0.5.0 — 2019-08-07
- 0.3.3 — 2018-04-27
- 0.3.2 — 2018-04-27
- 0.3.1 — 2018-04-26
- 0.3.0 — 2018-04-26
- 0.2.1 — 2018-02-14
- 0.2.0 — 2018-02-12
- 0.1.5 — 2018-02-12
- 0.1.3 — 2017-12-05
- 0.1.2 — 2017-05-19
- 0.1.0 — 2017-05-19
- … 2 more at https://npm.io/package/jq-web/versions

## README

[![npm badge](https://img.shields.io/npm/v/jq-web.svg)](https://www.npmjs.com/package/jq-web) [![Mentioned in Awesome jq](https://awesome.re/mentioned-badge.svg)](https://github.com/fiatjaf/awesome-jq)

# jq-web

This is a WebAssembly build of [jq](https://github.com/jqlang/jq), the command-line JSON processor.

It runs in the browser.

### Installation and use

```
npm install jq-web
```

```js
var jq = require('jq-web');

jq.then( jq => jq.json({
  a: {
    big: {
      json: [
        'full',
        'of',
        'important',
        'things'
      ]
    }
  }
}, '.a.big.json | ["empty", .[1], "useless", .[3]] | join(" ")')
```

The code above returns the string `"empty of useless things"`.

You could do the same using the promised API with `jq.promised.json({...}).then(result => {})`. That is useful if you're loading a `.mem` or `.wasm` file, as the library won't return the correct results until these files are asynchronously fetched by the Emscripten runtime.

### Webpack issues

#### `fs`
The Emscripten runtime will try to `require` the `fs` module, and if it fails it will resort to an in-memory filesystem (almost no use of that is made of the library, but it is needed somehow). In Browserify there's a default `{}` that corresponds to the `fs` module, but in Webpack you must [declare it as an empty module](https://github.com/fiatjaf/jq-web/issues/5#issuecomment-342694955).

#### 404 error when loading `.wasm` files
By default projects compiled with Emscripten look for `.wasm` files in the same directory that the `.js` file is run from. This causes issues when using webpack because name of the `.wasm` file is altered with a hash and can be placed in a different directory. To fix this problem you can use the [copy-webpack-plugin](https://github.com/webpack-contrib/copy-webpack-plugin) to copy the `jq.wasm` file to the same directory that the webpack bundle is placed.

## Reference

`jq-web` exports a promise that resolves to an object with `json` and `raw` methods.

`jq.json(<object>, <filter>) <object>` will take a Javascript object, or scalar, whatever, and dump it to JSON, then it will return whatever your filter outputs and try to convert that into a JS object.

`jq.raw(<json-string>, <filter>, <flags>) <raw-output>` will take a string that will be passed as it is to jq (like if you were doing `echo '<json-string>' | jq <filter>` on the command line) then return a string with the raw STDOUT response.

## Build

1. Install Emscripten. There have been several API changes over time; version 3.1.31
is known to work.
2. Clone this repository, and `cd` into it.
3. `make`
    * This may take a while if you have never run Emscripten before.

## Test
A handful of tests exist in `test.js`. These are a good place to start when verifying a build.
To run them, do `make test`.

You can test browser functionality by running:
`./node_modules/live-server/live-server.js --open="index.html"`.

---
_Source: https://npm.io/package/jq-web · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._