CLI: more control over language bindings

Author: clasonCreated Dec 12, 2025Updated Aug 23, 2026
Labelstemplates

Problem

The growing list of language bindings is confusing and tedious to handle for parser maintainers. Long-term, a discussion needs to be had on how to shift more of the burden on the people actually using these bindings (e.g., maintain them in an upstream repo so they can be pulled in as a dependency), but we can improve the situation in the short term with more discoverability and control.

In particular, a major pain point is that some of the "language binding" files are actually necessary for tree-sitter to work properly, so one cannot simply remove all generated files. As far as I can tell, these are

  • src/tree_sitter/*.h (required for compiling parsers and custom scanners)
  • package.json (required for npm install in case of dependencies)

EDIT: After looking into this further, this is more of a discoverability issue due to incomplete/misleading documentation and tree-sitter init -u not being able to update files (which is itself misleading/poorly documented).

EDIT 2: After thinking yet more about this, having to maintain these in a repo across frequent (potentially breaking) changes in the templates and the workflows is just too much maintenance pressure. Unless they need to be manually written (as for some split parsers), bindings generation should be part of the "publish" step/workflow.

Expected behavior

An updated list of (partially independent) suggestions that I believe would improve the situation:

  1. The default value should be false for all languages (any exceptions need to be very compelling).
  2. The documentation should be clearer about which files are generated, distinguishing tree-sitter files from language bindings. E.g., src/tree_sitter/*.h files should not be listed as "bindings" in the documentation. (#5129, #5152).
  3. The "additional files" for "development experience" should be controlled by a separate tree-sitter.json field (default TBD).

Bindings should be generated as part of the publish workflow (either through a tree-sitter publish command or workflow).