Node.js bindings for tree-sitter
  • JavaScript 59.6%
  • C++ 39.5%
  • Python 0.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-07-28 18:23:36 -06:00
.github Give token write permissions for gh release create (#288) 2026-07-28 18:23:36 -06:00
src Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
test Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
vendor Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
.editorconfig Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
.gitignore docs: document the TS types 2024-11-10 17:14:06 -05:00
.gitmodules Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
binding.gyp Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
index.js Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
LICENSE Initial commit 2014-03-06 09:04:37 -08:00
package-lock.json 0.25.1 (#265) 2026-01-06 14:11:31 -08:00
package.json 0.25.1 (#265) 2026-01-06 14:11:31 -08:00
README.md docs(readme): fix docs badge 2024-12-29 20:32:15 -05:00
tree-sitter.d.ts Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
tsconfig.json Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
tsconfig.typedoc.json Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00
typedoc.json Proper tree-sitter 0.25 support (#258) 2026-01-06 08:38:39 -08:00

Node Tree-sitter

CI npm docs

This module provides Node.js bindings to the [tree-sitter] parsing library.

Installation

npm install tree-sitter

Basic Usage

Prerequisites

First, you'll need a Tree-sitter grammar for the language you want to parse. There are many existing grammars, such as tree-sitter-javascript. These grammars can typically be installed with a package manager like NPM, so long as the author has published them.

npm install tree-sitter-javascript

You can also develop a new grammar by using the Tree-sitter CLI and following the docs.

Parsing Source Code

Once you've got your grammar, create a parser with that grammar.

const Parser = require('tree-sitter');
const JavaScript = require('tree-sitter-javascript');

const parser = new Parser();
parser.setLanguage(JavaScript);

Then you can parse some source code,

const sourceCode = 'let x = 1; console.log(x);';
const tree = parser.parse(sourceCode);

and inspect the syntax tree.

console.log(tree.rootNode.toString());

// (program
//   (lexical_declaration
//     (variable_declarator (identifier) (number)))
//   (expression_statement
//     (call_expression
//       (member_expression (identifier) (property_identifier))
//       (arguments (identifier)))))

const callExpression = tree.rootNode.child(1).firstChild;
console.log(callExpression);

// {
//   type: 'call_expression',
//   startPosition: {row: 0, column: 16},
//   endPosition: {row: 0, column: 30},
//   startIndex: 0,
//   endIndex: 30
// }

If your source code changes, you can update the syntax tree. This is much faster than the first parse.

// In the code, we replaced 'let' with 'const'.
// So, we set our old end index to 3, and our new end index to 5.
// Note that the end index is exclusive.
const newSourceCode = 'const x = 1; console.log(x);';
//                        ^ ^
// indices:               3 5
// points:            (0,3) (0,5)

tree.edit({
  startIndex: 0,
  oldEndIndex: 3,
  newEndIndex: 5,
  startPosition: {row: 0, column: 0},
  oldEndPosition: {row: 0, column: 3},
  newEndPosition: {row: 0, column: 5},
});

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, such as a rope or array, you can parse it by supplying a callback to parse instead of a string:

const sourceLines = [
  'let x = 1;',
  'console.log(x);'
];

const tree = parser.parse((index, position) => {
  let line = sourceLines[position.row];
  if (line) {
    return line.slice(position.column);
  }
});

Further Reading

It's recommended that you read the Tree-sitter documentation on using parsers to get a higher-level overview of the API. Once you're comfortable with the basics, you can explore the full API documentation, which should map closely to the C API, though there are some differences.