Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

treesitter

URL: https://github.com/nvim-treesitter/nvim-treesitter/

Maintainers: Austin Horstman

Provides an interface to tree-sitter for Neovim.

note

This module targets the nvim-treesitter main branch (the current standard) and enables features via Neovim's native treesitter APIs. For backwards compatibility, if the legacy master branch is detected at runtime, your settings are forwarded to require('nvim-treesitter.configs').setup().

Quick Start

{
  plugins.treesitter = {
    enable = true;
    highlight.enable = true;
    indent.enable = true;
    folding.enable = true;
  };
}

Features are enabled via Neovim's native APIs:

  • highlight.enable → Calls vim.treesitter.start() on FileType events
  • indent.enable → Sets indentexpr to use treesitter's indent function
  • folding.enable → Configures vim fold options to use vim.treesitter.foldexpr()

Installing Grammar Parsers

By default, all available grammars are installed via Nix. This provides reproducible builds, no runtime compilation, and offline availability.

Customize which parsers to install:

{
  plugins.treesitter = {
    enable = true;

    grammarPackages = with pkgs.vimPlugins.nvim-treesitter.builtGrammars; [
      bash
      json
      lua
      make
      markdown
      nix
      regex
      toml
      vim
      vimdoc
      xml
      yaml
    ];
  };
}

Verify installed parsers with :checkhealth vim.treesitter.

Via Runtime Installation

Parsers cannot be configured to auto-install. Instead:

  • Use :TSInstall <language> to install parsers manually
  • Use :TSUninstall <language> to remove parsers

Configure the parser installation directory if needed:

{
  plugins.treesitter.settings = {
    install_dir.__raw = "vim.fs.joinpath(vim.fn.stdpath('data'), 'site')";
  };
}

Custom Grammars

Build and install your own grammar:

{ pkgs, ... }:
let
  treesitter-nu-grammar = pkgs.tree-sitter.buildGrammar {
    language = "nu";
    version = "0.0.0+rev=0bb9a60";
    src = pkgs.fetchFromGitHub {
      owner = "nushell";
      repo = "tree-sitter-nu";
      rev = "0bb9a602d9bc94b66fab96ce51d46a5a227ab76c";
      hash = "sha256-A5GiOpITOv3H0wytCv6t43buQ8IzxEXrk3gTlOrO0K0=";
    };
    meta.homepage = "https://github.com/nushell/tree-sitter-nu";
  };
in
{
  programs.nixvim.plugins.treesitter = {
    enable = true;
    grammarPackages = pkgs.vimPlugins.nvim-treesitter.allGrammars ++ [ treesitter-nu-grammar ];

    # Register the parser to filetype
    languageRegister.nu = "nu";
  };

  programs.nixvim.extraPlugins = [ treesitter-nu-grammar ];
}

Verify with :checkhealth vim.treesitter.

plugins.treesitter.enable

Whether to enable treesitter.

Type: boolean

Default: false

Example: true

Declared by:

plugins.treesitter.package

The treesitter package to use.

Type: package

Default: pkgs.vimPlugins.nvim-treesitter

Declared by:

plugins.treesitter.autoLoad

Whether to automatically load treesitter when neovim starts.

Type: boolean

Default: false when lazy-loading is enabled.

Example: false

Declared by:

plugins.treesitter.grammarPackages

Grammar packages to install

Type: list of package

Default: config.plugins.treesitter.package.allGrammars

Example: pkgs.vimPlugins.nvim-treesitter.allGrammars

Declared by:

plugins.treesitter.languageRegister

This is a wrapping of the vim.treesitter.language.register function.

Register specific parsers to one or several filetypes.

The keys are the parser names and the values are either one or several filetypes.

Type: attribute set of ((list of string) or string convertible to it)

Default: { }

Example:

{
  cpp = "onelab";
  python = [
    "foo"
    "bar"
  ];
}

Declared by:

plugins.treesitter.nixGrammars

Whether to install grammars defined in grammarPackages.

Type: boolean

Default: true

Example: false

Declared by:

plugins.treesitter.nixvimInjections

Whether to enable Nixvim injections, e.g. highlighting extraConfigLua as lua.

Type: boolean

Default: true

Example: false

Declared by:

plugins.treesitter.settings

Options provided to the require('nvim-treesitter').setup function.

Type: lua value

Default: { }

Example:

{
  install_dir = lib.nixvim.mkRaw "vim.fs.joinpath(vim.fn.stdpath('data'), 'site')";
}

Declared by: