tree-sitter/lib/binding_web/CONTRIBUTING.md

Contributing

Code of Conduct

Contributors to Tree-sitter should abide by the Contributor Covenant.

Developing Web-tree-sitter

Prerequisites

To make changes to Web-tree-sitter, you should have:

1. Install Rust
2. Install Node.js
3. Install Docker or podman

Building

1. Clone and open the repository:

git clone https://github.com/tree-sitter/tree-sitter
cd ./tree-sitter

2. Fetch and build the grammars that are used for testing:

cargo xtask fetch-fixtures

3. Update the generated parser.c files:

cargo xtask generate-fixtures

4. Build the Wasm modules:

cargo xtask generate-fixtures --wasm

5. Navigate to the web binding directory

cd tree-sitter/lib/binding_web

6. Install the dependencies:

npm install

7. Build the library:

npm run build

Note

By default, the build process will emit an ES6 module. If you need a CommonJS module, export CJS to true, or just run CJS=true npm run build (or the equivalent command for Windows).

Tip

To build the library with debug information, you can run npm run build:debug. The CJS environment variable is still taken into account.

8. Run the tests

npm test

Note

We use vitest to run the tests. If you want to run a specific test, you can use the -t flag to pass in a pattern. If you want to run a specific file, you can just pass the name of the file as is. For example, to run the parser tests in test/parser.test.ts, you can run npm test parser. To run tests that have the name descendant somewhere, run npm test -- -t descendant.

For coverage information, you can run npm test -- --coverage.

Putting it together

The C side

There are several components that come together to build the final JS and Wasm files. First, we use emscripten in our xtask located at xtask/src/build_wasm.rs from the root directory to compile the Wasm files. Note that it's also possible to use a local version of Emscripten, the build script will check if you have it installed before falling back to Dockeror Podman. This Wasm module is output into the local lib folder, and is used only in src/bindings.ts to handle loading the Wasm module. The C code that is compiled into the Wasm module is located in at lib/tree-sitter.c, and contains all the necessary glue code to interact with the JS environment. If you need to update the imported functions from the tree-sitter library, or anywhere else, you must update lib/exports.txt. Lastly, the type information for the Wasm module is located at lib/tree-sitter.d.ts, and can be updated by running cargo xtask build-wasm --emit-tsd from the root directory.

The TypeScript side

The TypeScript library is a higher level abstraction over the Wasm module, and is located in src. This is where the public API is defined, and where the Wasm module is loaded and initialized. The TypeScript library is built into a single ES6 (or CommonJS) module, and is output into the same directory as package.json. If you need to update the public API, you can do so by editing the files in src.

If you make changes to the library that require updating the type definitions, such as adding a new public API method, you should run:

npm run build:dts

This uses dts-buddy to generate web-tree-sitter.d.ts from the public types in src. Additionally, a sourcemap is generated for the .d.ts file, which enables go-to definition and other editor integrations to take you straight to the TypeScript source code.

This TypeScript code is then compiled into a single JavaScript file with esbuild. The build configuration for this can be found in script/build.js, but this shouldn't need to be updated. This step is responsible for emitting the final JS and Wasm files that are shipped with the library, as well as their sourcemaps.

Debugging

You might have noticed that when you ran npm build, the build process generated a couple of sourcemaps: web-tree-sitter.js.map and web-tree-sitter.wasm.map. These sourcemaps can be used to debug the library in the browser, and are shipped with the library on both NPM and the GitHub releases.

Tweaking the Emscripten build

If you're trying to tweak the Emscripten build, or are trying to debug an issue, the code for this lies in xtask/src/build_wasm.rs file mentioned earlier, namely in the run_wasm function.