wasitter brings Tree-sitter to Go using the upstream C implementation. It compiles the Tree-sitter runtime and language parsers into WebAssembly, then loads and runs them inside Go programs with wazero.
- No CGO, C compiler, or system shared libraries required. Build and cross-compile with the standard Go toolchain.
- Tracks upstream releases and reuses the original parsing implementation, reducing the risk of bugs and the maintenance burden associated with a rewrite.
- Packages language support as individual WASM files that can be loaded on demand, without bundling every language by default.
- Provides a thin wrapper around the upstream API that follows Go conventions.
- Uses native comparison tests to check that key behaviors match upstream Tree-sitter.
WASM execution and calls between Go and WASM add overhead, so wasitter is slightly slower than the native implementation. I'll do my best to address unexpected performance issues.
Requires Go 1.23 or newer.
go get github.com/zema1/wasitter@latestJavaScript and JSON parsers are embedded in the package. The following example uses the built-in JavaScript parser:
package main
import (
"context"
"fmt"
"log"
"github.com/zema1/wasitter"
)
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
func run() error {
ctx := context.Background()
parser, runtime, err := wasitter.NewJavaScriptParser(ctx)
if err != nil {
return err
}
defer runtime.Close()
defer parser.Close()
source := []byte(`function greet(name) { return "Hello, " + name; }`)
tree, err := parser.ParseContext(ctx, source, nil)
if err != nil {
return err
}
defer tree.Close()
function := tree.RootNode().NamedChild(0)
name := function.ChildByFieldName("name")
fmt.Println(name.Content(source)) // greet
return nil
}The runtime executes the language module, and the parser turns source code into
a syntax tree. The example then finds the function node and reads its name field.
For JSON, create the parser with wasitter.NewJSONParser(ctx).
Download WASM files from the releases page. Choose the release that matches the wasitter version in your project. Mixing versions is unsupported and may lead to incorrect behavior.
There are currently 12 supported languages: JavaScript, JSON, Bash, C, C++, Go, Java, Python, Ruby, Rust, TypeScript, and TSX.
For Python, download wasitter-python.wasm to a location such as
grammars/wasitter-python.wasm, then load it as follows:
parser, runtime, err := wasitter.NewParserFromFile(ctx, "grammars/wasitter-python.wasm")
if err != nil {
return err
}
defer runtime.Close()
defer parser.Close()
source := []byte("def greet(name):\n return name\n")The constructor loads the grammar from the WASM module and returns a parser
that is ready to use. Then call ParseContext as in the quick start example.
If you already have the WASM bytes, for example through go:embed, use
wasitter.NewParserFromWASM(ctx, wasmBytes) instead.
- Reuse a parser and runtime when processing multiple files, and close each tree when you are done with it. For parallel parsing, give each worker its own runtime and parser.
- Keep a tree open while reading its nodes. Close trees, queries, and parsers
before closing the runtime. The examples use
deferto ensure this cleanup order; deferred calls run in reverse order. - A successful parse does not mean the source has no syntax errors. Tree-sitter
can produce a tree for incomplete code; check
tree.RootNode().HasError()separately for syntax errors. - Node positions use UTF-8 byte offsets and byte columns, not character counts or UTF-16 code-unit offsets.
The usage guide covers queries, incremental parsing, runtime configuration, and compatibility.
For instructions on adding languages, rebuilding WASM, running tests, and publishing releases, see DEVELOPMENT.md.
wasitter is licensed under the MIT License. License information for
the grammars, runtime, and toolchain is available in the
third-party notices.
When distributing WASM files, include THIRD_PARTY_NOTICES.txt from the same release.