Getting Started

Set up your development environment and create your first Tree-sitter parser

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 (Recommended)

cargo install tree-sitter-cli --locked

# Clone the repository
git clone https://github.com/tree-sitter/tree-sitter.git
cd tree-sitter

# Build the CLI
cd crates/cli
cargo build --release

npm install -g tree-sitter-cli

# Download from GitHub releases
curl -LO https://github.com/tree-sitter/tree-sitter/releases/latest/download/tree-sitter-linux-x64.gz
gunzip tree-sitter-linux-x64.gz
chmod +x tree-sitter-linux-x64
mv tree-sitter-linux-x64 /usr/local/bin/tree-sitter

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 <[e-mail]>
 * @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

Example with Autocompletion

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.