Getting Started

Dependencies

To develop a Tree-sitter parser, there are two dependencies that you need to install:

• A JavaScript runtime — Tree-sitter grammars are written in JavaScript, and Tree-sitter uses a JavaScript runtime (the default being Node.js) to interpret JavaScript files. It requires this runtime command (default: node) to be in one of the directories in your PATH.

• A C Compiler — Tree-sitter creates parsers that are written in C. To run and test these parsers with the tree-sitter parse or tree-sitter test commands, you must have a C/C++ compiler installed. Tree-sitter will try to look for these compilers in the standard places for each platform.

Installation

To create a Tree-sitter parser, you need to use the tree-sitter CLI. You can install the CLI in a few different ways:

• Build the tree-sitter-cli Rust crate from source using cargo, the Rust package manager. This works on any platform. See the contributing docs for more information.

• Install the tree-sitter-cli Rust crate from crates.io using cargo. You can do so by running the following command: cargo install tree-sitter-cli --locked

• Install the tree-sitter-cli Node.js module using npm, the Node package manager. This approach is fast, but it only works on certain platforms, because it relies on pre-built binaries.

• Download a binary for your platform from the latest GitHub release, and put it into a directory on your PATH.

Project Setup

The preferred convention is to name the parser repository “tree-sitter-” followed by the name of the language, in lowercase.

mkdir tree-sitter-${LOWER_PARSER_NAME}
cd tree-sitter-${LOWER_PARSER_NAME}

Note

The LOWER_ prefix here means the “lowercase” name of the language.

Warning

Dashes are not permitted via the CLI’s init command and should not be used in parser names.

Init

Once you’ve installed the tree-sitter CLI tool, you can start setting up your project, which will allow your parser to be used from multiple languages.

# This will prompt you for input
tree-sitter init

The init command will create a bunch of files in the project. There should be a file called grammar.js with the following contents:

/**
 * @file PARSER_DESCRIPTION
 * @author PARSER_AUTHOR_NAME PARSER_AUTHOR_EMAIL
 * @license PARSER_LICENSE
 */

/// <reference types="tree-sitter-cli/dsl" />
// @ts-check

export default grammar({
  name: 'LOWER_PARSER_NAME',

  rules: {
    // TODO: add the actual grammar rules
    source_file: $ => 'hello'
  }
});

Note

The placeholders shown above would be replaced with the corresponding data you provided in the init sub-command’s prompts.

To learn more about this command, check the reference page.

Generate

Next, run the following command:

tree-sitter generate

This will generate the C code required to parse this trivial language.

You can test this parser by creating a source file with the contents “hello” and parsing it:

echo 'hello' > example-file
tree-sitter parse example-file

Alternatively, in Windows PowerShell:

"hello" | Out-File example-file -Encoding utf8
tree-sitter parse example-file

This should print the following:

(source_file [0, 0] - [1, 0])

You now have a working parser.

Finally, look back at the triple-slash and @ts-check comments in grammar.js; these tell your editor to provide documentation and type information as you edit your grammar. For these to work, you must download Tree-sitter’s TypeScript API from npm into a node_modules directory in your project:

npm install # or your package manager of choice

To learn more about this command, check the reference page.