@ast-grep/wasm

WebAssembly build of ast-grep for use in browsers and Node.js.

This package provides the same API as @ast-grep/napi but runs in any JavaScript environment that supports WebAssembly, including browsers, Deno, and edge runtimes.

Installation

yarn add @ast-grep/wasm web-tree-sitter

web-tree-sitter is a required peer dependency.

Vite

When using Vite, you need to make tree-sitter.wasm available in your public directory. You can automate this with a postinstall script in your package.json (see web-tree-sitter setup):

"postinstall": "cp node_modules/web-tree-sitter/tree-sitter.wasm public"

Usage

Unlike @ast-grep/napi, this package has no predefined language support. All languages must be registered at runtime by loading their tree-sitter WASM parser.

import { initializeTreeSitter, registerDynamicLanguage, parse, kind } from '@ast-grep/wasm'

// 1. Initialize the tree-sitter WASM runtime (once)
await initializeTreeSitter()

// 2. Register a language by loading its WASM parser
await registerDynamicLanguage({
  javascript: { libraryPath: '/path/to/tree-sitter-javascript.wasm' },
})

// 3. Parse and search code
const sg = parse('javascript', 'console.log("hello world")')
const node = sg.root().find('console.log($ARG)')
console.log(node.getMatch('ARG').text()) // "hello world"

Registering Languages

registerDynamicLanguage accepts a map of language name to registration config. It can be called multiple times to add or update languages.

await registerDynamicLanguage({
  javascript: { libraryPath: '/path/to/tree-sitter-javascript.wasm' },
  python: {
    libraryPath: '/path/to/tree-sitter-python.wasm',
    expandoChar: 'µ',  // custom expando char for languages where $ is special
  },
})

The expandoChar option sets the character used internally to represent metavariables (defaults to $). Use a different character for languages where $ is a valid identifier character (e.g. PHP, Bash).

Pattern Matching

// By pattern string
sg.root().find('console.log($$$ARGS)')

// By kind number
const k = kind('javascript', 'call_expression')
sg.root().find(k)

// By rule config (same as YAML rules)
sg.root().find({
  rule: { pattern: 'console.log($A)' },
  constraints: { A: { kind: 'string' } },
})

Code Rewriting

const match = sg.root().find('console.log($A)')
const edit = match.replace('console.error($A)')
const newCode = sg.root().commitEdits([edit])

API Reference

Top-level functions

initializeTreeSitter(): Promise<void>

Initializes the tree-sitter WASM runtime. Must be called once before any other function.

registerDynamicLanguage(langs: Record<string, { libraryPath: string, expandoChar?: string }>): Promise<void>

Registers one or more language parsers by loading their WASM binaries. Can be called multiple times; existing languages are updated.

parse(lang: string, src: string): SgRoot

Parses source code and returns an SgRoot instance. Throws if the language has not been registered.

kind(lang: string, kindName: string): number

Returns the numeric kind ID for a named node type in the given language. Useful for matching by node kind.

pattern(lang: string, patternStr: string): object

Compiles a pattern string into a rule config object (equivalent to { rule: { pattern: patternStr } }). Useful for building rule configs programmatically.

dumpPattern(lang: string, patternStr: string, selector?: string, strictness?: string): PatternTree

Dumps the internal structure of a pattern for inspection and debugging. Returns a tree showing how ast-grep parses the pattern, including source positions and node kinds.

• selector: optional kind name for contextual patterns (e.g. 'field_definition')
• strictness: one of "cst", "smart" (default), "ast", "relaxed", "signature", "template"

Each PatternTree node has:

• kind: the tree-sitter node kind string
• pattern: "metaVar", "terminal", or "internal"
• isNamed: whether the node is a named node
• text: source text (for metavar and terminal nodes)
• children: child PatternTree nodes
• start, end: { line, column } positions in the pattern source

SgRoot

Represents the parsed tree of code.

root(): SgNode

Returns the root SgNode.

filename(): string

Returns "anonymous" when the instance is created via parse.

getInnerTree(): Tree

Returns the underlying web-tree-sitter Tree object. Useful for low-level inspection or debugging.

SgNode

Represents a single AST node.

Position and info

Searching

Matchers can be a pattern string, a kind number (from kind()), or a rule config object.

Relational matchers

Match environment

Tree traversal

Editing

WasmEdit has start_pos, end_pos (character offsets), and inserted_text. These fields can be modified before calling commitEdits.

Building from Source

Requires wasm-pack.

# For browser (ES module)
yarn build

# For Node.js (CommonJS)
yarn build:nodejs

# For bundlers
yarn build:bundler

Testing

yarn install

Rust WASM tests

yarn test

Note: wasm-pack test --node runs the test harness from a temporary directory. The test script sets NODE_PATH=$PWD/node_modules so that web-tree-sitter and parser WASM files can be resolved. If you run wasm-pack test --node directly, set NODE_PATH yourself:

NODE_PATH=$PWD/node_modules wasm-pack test --node

JavaScript tests

yarn test:js

This builds the WASM package for Node.js and runs AVA tests against it.