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

docs(web): update README and add CONTRIBUTING docs

Browse source
This commit is contained in:
Amaan Qureshi 2025-01-20 04:06:32 -05:00
parent 692332ed1c
commit f6a943a1ad
2 changed files with 182 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

56
lib/binding_web/README.md
View file

@ -7,9 +7,10 @@
WebAssembly bindings to the [Tree-sitter](https://github.com/tree-sitter/tree-sitter) parsing library.
### Setup
## Setup
You can download the `tree-sitter.js` and `tree-sitter.wasm` files from [the latest GitHub release](https://github.com/tree-sitter/tree-sitter/releases/latest) and load them using a standalone script:
You can download the `tree-sitter.js` and `tree-sitter.wasm` files from [the latest GitHub release][gh release] and load
them using a standalone script:
```html
<script src="/the/path/to/tree-sitter.js"></script>
@ -20,7 +21,7 @@ You can download the `tree-sitter.js` and `tree-sitter.wasm` files from [the lat
</script>
```
You can also install [the `web-tree-sitter` module](https://www.npmjs.com/package/web-tree-sitter) from NPM and load it using a system like Webpack:
You can also install [the `web-tree-sitter` module][npm module] from NPM and load it using a system like Webpack:
```js
const { Parser } = require('web-tree-sitter');
@ -50,13 +51,22 @@ await Parser.init();
// the library is ready
```
To install a debug version of the library, pass in `--debug` when running `npm install`:
To use the debug version of the library, replace your import of `web-tree-sitter` with `web-tree-sitter/debug`:
```sh
npm install web-tree-sitter --debug
```js
import { Parser } from 'web-tree-sitter/debug'; // or require('web-tree-sitter/debug')
Parser.init().then(() => { /* the library is ready */ });
```
This will load the debug version of the `.wasm` file, which includes sourcemaps for both the JS and WASM files, debug symbols, and assertions.
This will load the debug version of the `.js` and `.wasm` file, which includes debug symbols and assertions.
> [!NOTE]
> The `tree-sitter.js` file on GH releases is an ES6 module. If you are interested in using a pure CommonJS library, such
> as for Electron, you should note that on our NPM package, we use [conditional exports][cond export] to provide both the
> ES6 and CommonJS modules. If you've set up your project correctly, and need to use CommonJS, your package manager will
> automatically handle this for you. As of writing, we do not host a CommonJS version of the library on GH releases, and
> if you do not use the NPM registry, you'll have to build the library yourself.
### Basic Usage
@ -126,7 +136,8 @@ const newTree = parser.parse(newSourceCode, tree);
### Parsing Text From a Custom Data Structure
If your text is stored in a data structure other than a single string, you can parse it by supplying a callback to `parse` instead of a string:
If your text is stored in a data structure other than a single string, you can parse it by supplying a callback to `parse`
instead of a string:
```javascript
const sourceLines = [
@ -146,7 +157,8 @@ There are several options on how to get the `.wasm` files for the languages you
#### From npmjs.com
The recommended way is to just install the package from npm. For example, to parse JavaScript, you can install the `tree-sitter-javascript` package:
The recommended way is to just install the package from npm. For example, to parse JavaScript, you can install the `tree-sitter-javascript`
package:
```sh
npm install tree-sitter-javascript
@ -156,16 +168,19 @@ Then you can find the `.wasm` file in the `node_modules/tree-sitter-javascript`
#### From GitHub
You can also download the `.wasm` files from GitHub releases, so long as the repository uses our reusable workflow to publish them.
For example, you can download the JavaScript `.wasm` file from the tree-sitter-javascript [releases page](https://github.com/tree-sitter/tree-sitter-javascript/releases/latest)
You can also download the `.wasm` files from GitHub releases, so long as the repository uses our reusable workflow to publish
them.
For example, you can download the JavaScript `.wasm` file from the tree-sitter-javascript [releases page][gh release js].
#### Generating `.wasm` files
You can also generate the `.wasm` file for your desired grammar. Shown below is an example of how to generate the `.wasm` file for the JavaScript grammar.
You can also generate the `.wasm` file for your desired grammar. Shown below is an example of how to generate the `.wasm`
file for the JavaScript grammar.
**IMPORTANT**: [emscripten](https://emscripten.org/docs/getting_started/downloads.html), [docker](https://www.docker.com/), or [podman](https://podman.io) need to be installed.
**IMPORTANT**: [Emscripten][emscripten], [Docker][docker], or [Podman][podman] need to be installed.
First install `tree-sitter-cli` and the tree-sitter language for which to generate `.wasm` (`tree-sitter-javascript` in this example):
First install `tree-sitter-cli`, and the tree-sitter language for which to generate `.wasm`
(`tree-sitter-javascript` in this example):
```sh
npm install --save-dev tree-sitter-cli tree-sitter-javascript
@ -181,7 +196,8 @@ If everything is fine, file `tree-sitter-javascript.wasm` should be generated in
### Running .wasm in Node.js
Notice that executing `.wasm` files in node.js is considerably slower than running [node.js bindings](https://github.com/tree-sitter/node-tree-sitter). However could be useful for testing purposes:
Notice that executing `.wasm` files in Node.js is considerably slower than running [Node.js bindings][node bindings].
However, this could be useful for testing purposes:
```javascript
const Parser = require('web-tree-sitter');
@ -229,7 +245,7 @@ For more information on the module options you can pass in, see the [emscripten
#### "Can't resolve 'fs' in 'node_modules/web-tree-sitter"
Most bundlers will notice that the `tree-sitter.js` file is attempting to import `fs`, i.e. node's file system library.
Since this doesn't exist in the browser, the bundlers will get confused. For webpack you can fix this by adding the
Since this doesn't exist in the browser, the bundlers will get confused. For Webpack, you can fix this by adding the
following to your webpack config:
```javascript
@ -242,4 +258,12 @@ following to your webpack config:
}
```
[cond export]: https://nodejs.org/api/packages.html#conditional-exports
[docker]: https://www.docker.com
[emscripten]: https://emscripten.org
[emscripten-module-options]: https://emscripten.org/docs/api_reference/module.html#affecting-execution
[gh release]: https://github.com/tree-sitter/tree-sitter/releases/latest
[gh release js]: https://github.com/tree-sitter/tree-sitter-javascript/releases/latest
[node bindings]: https://github.com/tree-sitter/node-tree-sitter
[npm module]: https://www.npmjs.com/package/web-tree-sitter
[podman]: https://podman.io