# @willbooster/tree-sitter-javascript
[](https://www.npmjs.com/package/@willbooster/tree-sitter-javascript)
[](https://www.npmjs.com/package/@willbooster/tree-sitter-javascript)
[](https://github.com/WillBooster/tree-sitter-javascript/actions/workflows/test.yml)
[](https://github.com/WillBooster/tree-sitter-javascript/actions/workflows/test-rust.yml)
[](https://github.com/semantic-release/semantic-release)
[](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
[](https://crates.io/crates/willbooster-tree-sitter-javascript)
JavaScript and JSX grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter), forked from
[tree-sitter/tree-sitter-javascript](https://github.com/tree-sitter/tree-sitter-javascript). We are grateful
to its authors and contributors. This is not an official release of that project.
This fork fixes parsing bugs and raises conformance with [ECMAScript (ECMA-262)](https://tc39.es/ecma262/) and
[JSX](https://facebook.github.io/jsx/).
## Support Scope
This fork maintains only full parsing: valid input yields a correct tree, and invalid input yields `ERROR` or `MISSING`
nodes without crashing, hanging, or taking more than linear time. Incremental parsing works as in upstream tree-sitter
but is not tested here, and no queries (highlights, locals, injections, tags) are shipped. Node types, field names, and
the trees that error recovery produces may change; such changes are released as new major versions.
## Usage
The npm package ships two languages for
[@willbooster/web-tree-sitter](https://www.npmjs.com/package/@willbooster/web-tree-sitter), which runs in Node.js, Bun,
browsers, and Cloudflare Workers. The parser carries the ABI number of WillBooster/tree-sitter (`0x5742000c`), so it
requires that runtime ABI; the upstream runtime rejects it. This package is tested with runtime 17.0.1, and its optional peer dependency requires 17.0.1 or later within 17.x. In Node.js and Bun, load it from
the package. Choose `tree-sitter-javascript.wasm` for the Module goal, or
`tree-sitter-javascript_script.wasm` for the Script goal. The source goal comes from the host or file type;
`.mjs` uses Module and `.cjs` uses Script, while `.js` depends on the host. For example, `await\nvalue` is one
await expression in a Module and two identifier statements in a Script. Both languages preserve the same node
schema. As with other tree-sitter grammars, parsing does not enforce every ECMAScript early error.
For the native CLI, select Script with `tree-sitter parse --grammar-path grammars/script`.
```js
import { fileURLToPath } from 'node:url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
await Parser.init();
const parser = new Parser();
const wasmPath = fileURLToPath(import.meta.resolve('@willbooster/tree-sitter-javascript/tree-sitter-javascript.wasm'));
parser.setLanguage(await Language.load(wasmPath));
const tree = parser.parse('const App = () => <p>Hello</p>;\n');
```
In browsers, let your bundler serve the runtime and the selected language `.wasm` files, then pass their URLs.
For the Script goal, replace the language import below with
`@willbooster/tree-sitter-javascript/tree-sitter-javascript_script.wasm?url`:
```js
import javascriptUrl from '@willbooster/tree-sitter-javascript/tree-sitter-javascript.wasm?url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtimeUrl from '@willbooster/web-tree-sitter/web-tree-sitter.wasm?url'; // Vite
await Parser.init({ locateFile: () => runtimeUrl });
const parser = new Parser();
parser.setLanguage(await Language.load(javascriptUrl));
```
In Cloudflare Workers, which do not allow compiling Wasm at run time, import the runtime and the selected language
`.wasm` files as modules, with or without Node.js compatibility. For the Script goal, replace the language import
below with `@willbooster/tree-sitter-javascript/tree-sitter-javascript_script.wasm`:
```js
import javascript from '@willbooster/tree-sitter-javascript/tree-sitter-javascript.wasm';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtime from '@willbooster/web-tree-sitter/web-tree-sitter.wasm';
await Parser.init({ wasmModule: runtime });
const parser = new Parser();
parser.setLanguage(await Language.load(javascript));
```
The package also ships the node types in `src/node-types.json`, `tree-sitter.json`, and `grammar.js` for grammars
that extend this one (e.g. `require('@willbooster/tree-sitter-javascript/grammar')`). Its JSDoc describes the
array/formal and object-rest extension hooks. Their external scanners can include `src/literal.h`, which scans template
characters and escapes and JSX text for the tokens they pass it. The crate ships `tree-sitter.json` too.
In Rust, depend on the [crate](https://crates.io/crates/willbooster-tree-sitter-javascript) and the
[willbooster-tree-sitter](https://crates.io/crates/willbooster-tree-sitter) runtime with the matching ABI. The tested version is 17.0.1:
```sh
cargo add willbooster-tree-sitter@17.0.1 --rename tree-sitter
cargo add willbooster-tree-sitter-javascript --rename tree-sitter-javascript
```
```rust
let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_javascript::LANGUAGE.into())?;
// Use LANGUAGE_SCRIPT for the Script goal.
```
## Development
```sh
mise install
bun install --frozen-lockfile
bun run build/ci
bun run test
script/parse-examples
cargo test
```
Every `tree-sitter` command, from `generate` to the tests, runs the CLI of the WillBooster/tree-sitter runtime version
locked in `Cargo.lock` (`script/tree-sitter`), whose generator and runtime have fixes that the upstream CLI lacks.
`script/fork-cli` downloads that CLI into `.tmp/` from its GitHub Release on first use, or builds it with `cargo` when
the download fails or the release has no binary that runs here.
`bun run generate` records a fresh generation profile from the applicable `test/corpus` cases and Git-tracked
files in `examples/`, then generates compact parser tables. The parser also embeds metadata from `tree-sitter.json`. After changing a grammar,
`tree-sitter.json`, a corpus case, or a tracked example,
regenerate and commit the affected grammar's `src/` directory. Stage added or removed examples with `git add -A examples` before generation so the profile uses the intended file list.
Profiles in `.tmp/generation-profiles/` are temporary and must not be committed. `bun run build-wasm`, `bun run build/ci`,
and the release build regenerate the parsers before compiling them.
`bun run test` runs:
- the corpus in `test/corpus`, with the native build and with the Wasm build (the first run downloads the WASI SDK);
- a check that the real-world JavaScript files in `examples/`, the checked-in ones and those of the cloned repository,
fail to parse exactly as listed in `script/known-failures.txt`. The first run clones the repository. The example
repository is pinned to a commit in `script/parse-examples`. After a grammar change or a moved pin alters that list,
`script/parse-examples` rewrites it; review its diff before committing;
- a performance check (`test/unit/performance.test.ts`) that recovering from an error on each line takes linear time
(ten times the lines take about ten times the CPU time), since consumers parse files while they are being edited.
It loads the Wasm build through @willbooster/web-tree-sitter, which `bun run build/ci` rebuilds after regenerating
the parser;
- checks that the Wasm build parses in Chromium (`test/unit/browser/`) and in Cloudflare Workers with and without
Node.js compatibility (`test/unit/workers.test.ts`). Run `bun run test/ci-setup` once before the first
run to install Chromium and, on Linux, the system libraries it needs;
- a check that `package.json` and `Cargo.lock` lock the same WillBooster/tree-sitter runtime version
(`test/unit/runtimeVersion.test.ts`).
The tests and `script/parse-examples` compile the parser into `.tmp/tree-sitter-lib` instead of the CLI's cache shared
by every checkout, and `mise.toml` sets `TREE_SITTER_LIBDIR` to it for any other command run in the checkout.
CI also runs these tests on Linux arm64 and macOS, where the Rust binding compiles the parser natively, and fuzzes the
parser with libFuzzer and sanitizers (`.github/workflows/robustness.yml`).
### References
- [The ESTree Spec](https://github.com/estree/estree)
- [The ECMAScript 2025 Spec](https://tc39.es/ecma262/2025/)