Skip to main content

​
Getting Started

This guide will walk you through setting up your development environment and creating your first Tree-sitter parser.

​
Dependencies

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

​
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.
The runtime command (default: node) must be in one of the directories in your PATH.

​
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 compilers in the standard places for each platform (gcc, clang, or MSVC).

​
Installation

You can install the Tree-sitter CLI in several ways: 
cargo install tree-sitter-cli --locked
The npm installation method is fast but only works on certain platforms because it relies on pre-built binaries.

​
Project Setup

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

Create the project directory

mkdir tree-sitter-mylang
cd tree-sitter-mylang
Replace mylang with the lowercase name of your language.
2

Initialize the project

tree-sitter init
This command will prompt you for:
  • Language name
  • Parser description
  • Author information
  • License
The CLI will create the necessary project structure and files.
3

Review the generated files

The init command creates several files:
  • grammar.js - Your grammar definition
  • package.json - Node.js package configuration
  • Cargo.toml - Rust package configuration
  • bindings/ - Language bindings
  • src/ - Generated parser code (created later)

​
Your First Grammar

After initialization, you’ll have a grammar.js file with the following structure:
grammar.js
/**
 * @file Parser for MyLang
 * @author Your Name <[email protected]>
 * @license MIT
 */

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

export default grammar({
  name: 'mylang',

  rules: {
    // TODO: add the actual grammar rules
    source_file: $ => 'hello'
  }
});
The triple-slash reference and @ts-check comments enable TypeScript type checking and autocompletion in your editor.

​
Understanding the Template

Let’s break down the key parts:
  • File header - Documentation comments with description, author, and license
  • Type reference - Enables IDE support for the grammar DSL
  • Export - The grammar object is exported as the default export
  • Name - Must match your language name
  • Rules - Define the structure of your language

​
Generate the Parser

Now generate the C code for your parser:
1

Run the generate command

tree-sitter generate
This creates the parser code in the src/ directory:
  • parser.c - The generated parser
  • tree_sitter/parser.h - Header file
  • node-types.json - Node type definitions
2

Test the parser

Create a test file:
echo 'hello' > example-file
tree-sitter parse example-file
You should see:
(source_file [0, 0] - [1, 0])
The numbers in brackets [0, 0] - [1, 0] represent the position in the file: [row, column] for start and end.

​
Enable IDE Support

For the best development experience, install the Tree-sitter TypeScript definitions: 
npm install
This downloads the TypeScript API and enables:
  • Autocompletion - Suggestions for grammar DSL functions
  • Type checking - Catch errors before generating
  • Documentation - Inline docs for all functions
export default grammar({
  name: 'mylang',
  
  rules: {
    source_file: $ => repeat($._statement),
    
    _statement: $ => choice(
      $.return_statement,
      $.expression_statement
    ),
    
    // Your editor will suggest: seq, choice, repeat, optional, etc.
  }
});

​
Development Commands

Here are the essential commands you’ll use during development:

tree-sitter generate

Generate the parser from your grammar

tree-sitter test

Run all tests in test/corpus/

tree-sitter parse

Parse a file and display the syntax tree

tree-sitter build

Compile the parser as a shared library

​
Parse Command Options

# Show debug output
tree-sitter parse --debug example.txt

# Show debug graph (requires graphviz)
tree-sitter parse --debug-graph example.txt

# Parse as XML
tree-sitter parse --xml example.txt

# Time the parse
tree-sitter parse --time example.txt

​
Next Steps

Now that you have a working parser, you’re ready to:
  1. Learn about the Grammar DSL functions
  2. Start Writing Grammar rules
  3. Add Tests for your parser
Start by examining existing Tree-sitter parsers on GitHub to see real-world examples. The tree-sitter organization maintains parsers for many popular languages.

Build docs developers (and LLMs) love

Get started for freeTalk to us