node-tree-sitter

tree-sitter is the official Node.js binding for the tree-sitter parsing library, giving JavaScript and TypeScript code a way to parse source text into a concrete syntax tree using any of the many tree-sitter grammars (JavaScript, Python, Rust, HTML, and dozens more published separately on npm). The API mirrors the underlying C library closely: construct a Parser, call setLanguage() with a compiled grammar, then parse() a string (or a chunked custom-input callback) to get back a Tree you can query, walk, or re-parse incrementally after edits.

Because re-parsing reuses the previous syntax tree via tree.edit() plus an oldTree argument, the library is fast enough to run on every keystroke, which is why it underpins syntax highlighting, code folding, structural selection, and refactoring tooling in editors and IDE-like tools. The native addon is distributed with prebuilt binaries for macOS, Linux, and Windows on both x64 and arm64, so most consumers never need a local C++ toolchain to install it.

What You Get

• A Parser class that accepts any compiled tree-sitter grammar via setLanguage() and turns source text into a queryable syntax Tree
• Incremental re-parsing: edit a previous Tree with tree.edit() and pass it back into parse() so only the changed region is re-analyzed
• A Query API for running tree-sitter query-language patterns against a syntax tree to find and capture specific node types
• TreeCursor and LookaheadIterator classes for efficient tree traversal and grammar-aware autocomplete-style lookahead
• Prebuilt native binaries (via prebuildify/node-gyp-build) for macOS, Linux, and Windows across x64 and arm64, avoiding a local build step for most installs
• Full TypeScript declarations (tree-sitter.d.ts) with TSDoc comments covering the entire public API

Common Use Cases

• Building editor features like syntax highlighting, code folding, and bracket matching that need a real syntax tree rather than regex
• Powering structural search-and-replace or refactoring tools that need to find specific syntax node patterns via the Query API
• Implementing custom linters or static-analysis passes over source code without hand-writing a parser
• Enabling incremental, low-latency parsing in language servers or REPL-like tools where source text changes on every keystroke

Under The Hood

Architecture The addon follows a thin JS wrapper (index.js) around a native N-API C++ binding (src/binding.cc registers Parser, Query, Tree, TreeCursor, NodeMethods, and LookaheadIterator classes) that itself statically links the vendored tree-sitter C library (vendor/tree-sitter/lib/src/lib.c), declared as a separate static_library target in binding.gyp. Execution starts in index.js, which loads the platform-specific compiled addon via node-gyp-build (or a Bun-specific prebuild path), then extends several prototype methods (Tree.prototype.rootNode, Tree.prototype.edit, the SyntaxNode class) to marshal data between JS and the native TSNode/TSTree structures via module-level marshalNode/unmarshalNode helpers. Each native class (parser.cc, tree.cc, tree_cursor.cc, query.cc, node.cc, language.cc, lookaheaditerator.cc) maps closely to one tree-sitter C API concept, keeping a clean separation between JS ergonomics (index.js) and native parsing (src/*.cc plus the vendored C core) — the incremental-parsing algorithm itself lives entirely in the vendored library and is untouched by consumers.

Tech Stack Distributed as a native npm package built with node-addon-api (^8.5.0) and node-gyp-build (^4.8.4) at install/runtime, with node-gyp and prebuildify (^6.0.1) driving the multi-platform build so consumers get prebuilt binaries instead of compiling from source. The native layer is C++ (C++17 or C++20 depending on the target Node version, chosen dynamically in binding.gyp) wrapping a vendored, statically-linked copy of the tree-sitter C runtime, with N-API providing the ABI-stable bridge to V8. TypeScript typings (tree-sitter.d.ts) and a typedoc-based docs pipeline round out the developer-facing surface. CI runs Node’s built-in test runner across Windows/macOS/Linux (Intel and ARM) and four Node major versions, and grammar packages (tree-sitter-javascript, tree-sitter-python, tree-sitter-rust, etc.) are pulled in only as devDependencies for the test suite, not as runtime dependencies.

Code Quality The test suite (five files under test/, spanning tens of thousands of lines combined) uses Node’s built-in node:test runner rather than an external framework, exercising both the JS wrapper and native bindings against real grammars. Native C++ code favors RAII-style Napi::ObjectWrap patterns and explicit reference cleanup, but inline comments are sparse in the .cc/.h files — correctness is asserted mostly through tests rather than documented in-line. tsconfig.json enables strict type-checking against the test files and the hand-written declarations, and CI enforces the full OS/Node-version matrix before merge, giving reasonable confidence despite light in-source documentation.

API Design The public JS API stays close to the underlying C API — new Parser(), parser.setLanguage(…), parser.parse(sourceCode, oldTree) — while layering in JS ergonomics like accepting either a string or a chunked custom-input callback for parse(), and an oldTree argument for fast incremental re-parsing after edits. tree.edit() mirrors the C API’s byte/point-based edit description precisely, keeping the mental model consistent with upstream tree-sitter docs, though it does require understanding byte offsets and row/column points up front. Extensive TSDoc comments in tree-sitter.d.ts (including deprecation notes, e.g. steering users from getTimeoutMicros/setTimeoutMicros toward progressCallback) give IDE users inline guidance, and the README walks through parse, edit, and custom-input-callback usage with runnable snippets.