Parser Class

API reference for the Tree-sitter Parser class in JavaScript/Wasm

The Parser class is the main interface for parsing source code. It is a stateful object that produces a Tree based on source code input.

Initialization

Parser.init(moduleOptions?)

Initialize the Tree-sitter library. This must be called before creating any Parser instances.

static async init(moduleOptions?: Partial<EmscriptenModule>): Promise<void>

Parameters:

• moduleOptions (optional) - Options to configure the WebAssembly module
  • locateFile?: (scriptName: string, scriptDirectory: string) => string - Function to locate the .wasm file

Example:

import { Parser } from 'web-tree-sitter';

// Basic initialization
await Parser.init();

// With custom locate function (e.g., for Next.js)
await Parser.init({
  locateFile(scriptName, scriptDirectory) {
    return `/wasm/${scriptName}`;
  },
});

Constructor

new Parser()

Create a new parser instance.

const parser = new Parser();

You must call Parser.init() before constructing a parser, or a runtime error will be thrown.

Properties

language

The parser’s current language.

language: Language | null

Example:

const lang = parser.language;
if (lang) {
  console.log('Parser language:', lang.name);
}

Methods

setLanguage(language)

Set the language that the parser should use for parsing.

setLanguage(language: Language | null): this

Parameters:

• language - A Language object loaded from a .wasm file, or null to unset

Returns: The parser instance (for method chaining)

Throws: If the language version is incompatible with the current library version

Example:

import { Language } from 'web-tree-sitter';

const JavaScript = await Language.load('/tree-sitter-javascript.wasm');
parser.setLanguage(JavaScript);

// Can be chained
parser.setLanguage(JavaScript).parse(sourceCode);

parse(input, oldTree?, options?)

Parse source code and create a syntax tree.

parse(
  input: string | ParseCallback,
  oldTree?: Tree | null,
  options?: ParseOptions
): Tree | null

Parameters:

• input - Either a string of source code, or a callback function that returns text chunks
• oldTree (optional) - A previous syntax tree for incremental parsing. If provided, it must have been edited with tree.edit() to match the new text
• options (optional) - Parsing options
  • includedRanges?: Range[] - Array of ranges to parse (default: entire document)
  • progressCallback?: (state: ParseState) => void - Called periodically during parsing

Returns: A Tree object, or null if:

• The parser has no language assigned
• The progress callback cancelled parsing by returning true

Example with string input:

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

Example with callback:

const lines = ['function foo() {', '  return 42;', '}'];

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

Example with incremental parsing:

// Parse original code
const tree1 = parser.parse('let x = 1;');

// Edit the tree to match the new text
tree1.edit({
  startIndex: 0,
  oldEndIndex: 3,
  newEndIndex: 5,
  startPosition: { row: 0, column: 0 },
  oldEndPosition: { row: 0, column: 3 },
  newEndPosition: { row: 0, column: 5 },
});

// Re-parse with the old tree
const tree2 = parser.parse('const x = 1;', tree1);

Example with included ranges:

// Parse only JavaScript within HTML script tags
const tree = parser.parse(sourceCode, null, {
  includedRanges: [
    {
      startIndex: 100,
      endIndex: 200,
      startPosition: { row: 5, column: 0 },
      endPosition: { row: 10, column: 0 },
    },
  ],
});

Example with timeout:

const startTime = Date.now();
const tree = parser.parse(sourceCode, null, {
  progressCallback: (state) => {
    // Cancel parsing after 1 second
    if (Date.now() - startTime > 1000) {
      return true;
    }
  },
});

if (!tree) {
  console.log('Parsing timed out');
}

reset()

Instruct the parser to start the next parse from the beginning.

reset(): void

If the parser previously failed because of a callback, by default it will resume where it left off. Call reset() if you want to parse a different document instead.

Example:

parser.parse(callback1); // May fail mid-parse
parser.reset();          // Start fresh
parser.parse(callback2); // Parse from beginning

getIncludedRanges()

Get the ranges of text that the parser will include when parsing.

getIncludedRanges(): Range[]

Returns: Array of ranges that were set via parse() options, or a default range covering the entire document

Example:

const ranges = parser.getIncludedRanges();
console.log('Parsing ranges:', ranges);

setLogger(callback)

Set a logging callback for debugging the parser.

setLogger(callback: LogCallback | boolean | null): this

Parameters:

• callback - A function to receive log messages, or false/null to disable logging
  • LogCallback: (message: string, isLex: boolean) => void

Returns: The parser instance (for method chaining)

Example:

parser.setLogger((message, isLex) => {
  console.log(`[${isLex ? 'LEX' : 'PARSE'}] ${message}`);
});

parser.parse('x + y');
// Logs:
// [PARSE] reduce sym:program, child_count:1
// [PARSE] accept

// Disable logging
parser.setLogger(false);

getLogger()

Get the parser’s current logger callback.

getLogger(): LogCallback | null

Returns: The current logger function, or null if no logger is set

Example:

const logger = parser.getLogger();
if (logger) {
  console.log('Logger is active');
}

delete()

Delete the parser and free its resources.

delete(): void

Example:

const parser = new Parser();
// ... use parser ...
parser.delete(); // Clean up

While the library uses FinalizationRegistry for automatic cleanup when available, explicitly calling delete() is recommended for deterministic resource management.

Types

ParseOptions

Options for configuring the parsing process.

interface ParseOptions {
  includedRanges?: Range[];
  progressCallback?: (state: ParseState) => void;
}

ParseState

Represents the current state of the parser, passed to the progress callback.

interface ParseState {
  currentOffset: number; // Current byte offset in the document
  hasError: boolean;     // Whether an error has been encountered
}

Constants

LANGUAGE_VERSION

The latest ABI version supported by the current library version.

const LANGUAGE_VERSION: number;

MIN_COMPATIBLE_VERSION

The earliest ABI version supported by the current library version.

const MIN_COMPATIBLE_VERSION: number;

Example:

import { LANGUAGE_VERSION, MIN_COMPATIBLE_VERSION } from 'web-tree-sitter';

const language = await Language.load('/tree-sitter-javascript.wasm');
const version = language.abiVersion;

if (version < MIN_COMPATIBLE_VERSION || version > LANGUAGE_VERSION) {
  console.error('Incompatible language version');
}

See Also

• Tree class - Working with syntax trees
• Node class - Traversing and inspecting nodes
• Query API - Pattern matching on syntax trees