traxys/tree-sitter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(web): add WASM version compatibility section

Browse source 
Add documentation about version compatibility requirements between
web-tree-sitter and tree-sitter-cli for WASM file generation.

This helps users understand why Language.load() might fail when using
pre-built WASM files from third-party packages that were built with
incompatible tree-sitter-cli versions.

Closes #5171
This commit is contained in:
Kyuhwan Lee 2025-12-26 19:51:01 +09:00
parent ba7350c7ee
commit a2ca59838e
1 changed files with 23 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

23
lib/binding_web/README.md
View file

@ -191,6 +191,29 @@ npx tree-sitter build --wasm node_modules/tree-sitter-javascript
If everything is fine, file `tree-sitter-javascript.wasm` should be generated in current directory.
### WASM Version Compatibility
> [!IMPORTANT]
> WASM language files must be generated with a compatible version of `tree-sitter-cli`.
The WASM binary format includes ABI (Application Binary Interface) information that must match between `web-tree-sitter` and the generated `.wasm` files. Using incompatible versions will cause `Language.load()` to fail.
| web-tree-sitter | Compatible tree-sitter-cli |
|-----------------|---------------------------|
| 0.26.x | 0.26.x |
| 0.25.x | 0.20.x - 0.25.x |
| 0.24.x | 0.20.x - 0.24.x |
**If you're using pre-built WASM files** from third-party packages (e.g., `tree-sitter-wasms`), ensure they were built with a compatible `tree-sitter-cli` version.
**Recommended**: Generate WASM files with the same major.minor version of `tree-sitter-cli` as your `web-tree-sitter` version:
```sh
# For web-tree-sitter@0.26.x, use tree-sitter-cli@0.26.x
npm install tree-sitter-cli@0.26
npx tree-sitter build --wasm node_modules/tree-sitter-javascript
```
### Running .wasm in Node.js
Notice that executing `.wasm` files in Node.js is considerably slower than running [Node.js bindings][node bindings].