Wasm Support

API reference for WebAssembly grammar support in Rust

Tree-sitter’s Rust bindings support loading grammar files compiled to WebAssembly. This allows you to use languages without needing to compile them natively.

Wasm support requires enabling the wasm feature in your Cargo.toml:

[dependencies]
tree-sitter = { version = "0.24", features = ["wasm"] }

WasmStore

A WasmStore manages WebAssembly language instances.

new

pub fn new(engine: &wasmtime::Engine) -> Result<Self, WasmError>

Create a new Wasm store.

engine · &wasmtime::Engine · required

The Wasmtime engine to use for executing WebAssembly code

Returns: Ok(WasmStore) on success, or Err(WasmError) if the store could not be created.

use tree_sitter::{wasmtime::Engine, WasmStore};

let engine = Engine::default();
let store = WasmStore::new(&engine).unwrap();

load_language

pub fn load_language(&mut self, name: &str, bytes: &[u8]) -> Result<Language, WasmError>

Load a language from a Wasm file.

name · &str · required

The name of the language (for debugging purposes)

bytes · &[u8] · required

The bytes of the compiled Wasm file

Returns: Ok(Language) on success, or Err(WasmError) if the language could not be loaded.

const JAVASCRIPT_GRAMMAR: &[u8] = include_bytes!("path/to/tree-sitter-javascript.wasm");

let mut store = WasmStore::new(&engine).unwrap();
let javascript = store
    .load_language("javascript", JAVASCRIPT_GRAMMAR)
    .unwrap();

language_count

pub fn language_count(&self) -> usize

Get the number of languages currently loaded in this store.

println!("Loaded languages: {}", store.language_count());

Parser Extensions

When the wasm feature is enabled, the Parser struct gains additional methods for working with WebAssembly.

set_wasm_store

pub fn set_wasm_store(&mut self, store: WasmStore) -> Result<(), LanguageError>

Set the Wasm store that the parser should use. This is required before you can parse with a Wasm-based language.

store · WasmStore · required

The Wasm store to use

Returns: Ok(()) on success, or Err(LanguageError) if the store could not be set.

let mut parser = Parser::new();
parser.set_wasm_store(store).unwrap();

The store may be loaded from a different WasmStore than the one set on the parser, but it must use the same underlying WasmEngine.

take_wasm_store

pub fn take_wasm_store(&mut self) -> Option<WasmStore>

Take ownership of the parser’s Wasm store, removing it from the parser.

Returns: Some(WasmStore) if the parser has a store, or None if it doesn’t.

if let Some(store) = parser.take_wasm_store() {
    println!("Took Wasm store with {} languages", store.language_count());
}

Language Extensions

When the wasm feature is enabled, the Language struct gains additional methods.

is_wasm

pub fn is_wasm(&self) -> bool

Check if this language is loaded from WebAssembly.

if language.is_wasm() {
    println!("This is a Wasm-based language");
}

WasmError

Errors that can occur when working with WebAssembly grammars.

pub struct WasmError {
    pub kind: WasmErrorKind,
    pub message: String,
}

kind · WasmErrorKind

The kind of error that occurred

message · String

A human-readable error message

WasmErrorKind

pub enum WasmErrorKind {
    Parse,
    Compile,
    Instantiate,
    Other,
}

Parse · variant

Failed to parse the Wasm file

Compile · variant

Failed to compile the Wasm file

Instantiate · variant

Failed to instantiate the Wasm module

Other · variant

An unknown error occurred

Complete Example

Here’s a complete example of using WebAssembly grammars:

use tree_sitter::{wasmtime::Engine, Parser, WasmStore};

// Include the Wasm grammar file at compile time
const JAVASCRIPT_GRAMMAR: &[u8] = include_bytes!("tree-sitter-javascript.wasm");

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a Wasmtime engine
    let engine = Engine::default();
    
    // Create a Wasm store
    let mut store = WasmStore::new(&engine)?;
    
    // Load the JavaScript grammar
    let javascript = store.load_language("javascript", JAVASCRIPT_GRAMMAR)?;
    
    // Create a parser and set the Wasm store
    let mut parser = Parser::new();
    parser.set_wasm_store(store)?;
    
    // Set the language
    parser.set_language(&javascript)?;
    
    // Parse some code
    let source_code = "let x = 1;";
    let tree = parser.parse(source_code, None).unwrap();
    
    // Use the tree
    println!("Root: {}", tree.root_node().to_sexp());
    
    Ok(())
}

Using Multiple Wasm Languages

use tree_sitter::{wasmtime::Engine, Parser, WasmStore};

const JAVASCRIPT_GRAMMAR: &[u8] = include_bytes!("tree-sitter-javascript.wasm");
const PYTHON_GRAMMAR: &[u8] = include_bytes!("tree-sitter-python.wasm");

let engine = Engine::default();
let mut store = WasmStore::new(&engine).unwrap();

// Load multiple languages into the same store
let javascript = store.load_language("javascript", JAVASCRIPT_GRAMMAR).unwrap();
let python = store.load_language("python", PYTHON_GRAMMAR).unwrap();

println!("Loaded {} languages", store.language_count());

// Use the languages
let mut parser = Parser::new();
parser.set_wasm_store(store).unwrap();

// Parse JavaScript
parser.set_language(&javascript).unwrap();
let js_tree = parser.parse("const x = 1;", None).unwrap();

// Parse Python
parser.set_language(&python).unwrap();
let py_tree = parser.parse("x = 1", None).unwrap();

Performance Considerations

While WebAssembly grammars provide flexibility, there are some performance considerations:

• Initialization: Loading and compiling Wasm modules has a one-time cost
• Runtime: Wasm-based parsers are generally slightly slower than native parsers
• Memory: Each WasmStore maintains its own runtime state

For best performance:

• Reuse WasmStore instances when possible
• Load languages once during application startup
• Consider using native grammars for performance-critical applications

Error Handling

use tree_sitter::{WasmError, WasmErrorKind};

match store.load_language("javascript", JAVASCRIPT_GRAMMAR) {
    Ok(language) => {
        println!("Loaded language successfully");
    }
    Err(WasmError { kind, message }) => {
        match kind {
            WasmErrorKind::Parse => {
                eprintln!("Failed to parse Wasm file: {}", message);
            }
            WasmErrorKind::Compile => {
                eprintln!("Failed to compile Wasm: {}", message);
            }
            WasmErrorKind::Instantiate => {
                eprintln!("Failed to instantiate module: {}", message);
            }
            WasmErrorKind::Other => {
                eprintln!("Unknown error: {}", message);
            }
        }
    }
}