Skip to main content
docs/guides/custom-languages

Custom languages

Highlight a language CodePad doesn't ship, from your own tree-sitter grammar, without publishing it.

Edit this page

A custom language is a language package that you build from your own tree-sitter grammar, so the editor can highlight a language CodePad doesn't ship.

The package stays in your project. CodePad builds it from your grammar folder and doesn't publish it.

Prepare the grammar​

Run tree-sitter generate with tree-sitter 0.26 in your grammar folder. The command reads this layout:

my-grammar/
package.json optional, gives the version and the author
src/
parser.c
scanner.c optional
tree_sitter/
queries/
highlights.scm
injections.scm optional

A scanner must be written in C, and every file it includes, directly or through a header, must be inside src/.

Build the package​

Run the command that ships with react-native-codepad from your app's root:

npx react-native-codepad language ./my-grammar

It writes the package to modules/codepad-lang-<id>, where <id> is the name in the parser's tree_sitter_<id> function. The package is private and UNLICENSED. Its peer dependency accepts the CodePad version that built it and any later release with the same minor version.

FlagDefaultWhat it sets
--id <id>The parser's nameThe value you pass to language
--out <dir>modules/codepad-lang-<id>The folder the package is written to
--name <name>codepad-lang-<id>The npm name in the package's package.json

Run the command again after you change the grammar or its queries, and after you upgrade CodePad. It replaces the package it wrote before.

The command stops with a message, and doesn't write anything, when:

  • the id doesn't start with a lowercase letter, or holds anything other than lowercase letters, digits and underscores
  • the id is a Kotlin or Java keyword, or the id of a language CodePad ships
  • the grammar has the name of a language CodePad ships, as a fork of one does (rename it in grammar.js and generate again)
  • a query uses a predicate the editor can't run, or starts with an ; inherits: line
  • the parser comes from a tree-sitter version the editor can't load (generate it again with tree-sitter 0.26)
  • the scanner is C++ (scanner.cc), or a file in src/ includes one from outside it
  • the output folder exists and the command didn't write it

In an Expo app, autolinking picks up every package under modules/, and you don't add a dependency entry. In a bare React Native app, or if autolinking doesn't list the package, add it as a local dependency:

package.json
{
"dependencies": {
"codepad-lang-mylang": "file:./modules/codepad-lang-mylang"
}
}

Rebuild the app. On iOS, run pod install first.

caution

On Android, React Native reuses its autolinking result until a lockfile changes, so the first build after you add a folder to modules/ can leave the package out. Delete android/build/generated/autolinking/autolinking.json once and build again.

Pass the id to the editor:

<CodeEditor language="mylang" />

Codepad.availableLanguages() lists the id once the rebuilt app is running.

Queries​

Each capture in highlights.scm takes the theme style of the same name, so @keyword paints in keyword and @string.special falls back to string. The themes guide lists the keys.

The editor runs eq?, match? and contains? with their not- and any- forms. It also runs any-of?, has-parent? and has-ancestor? with their not- forms. lua-match? and vim-match? patterns are converted to match?.

A highlights query that references a node the grammar doesn't have makes the whole language fall back to plain text. Check each query against a sample file with tree-sitter query queries/highlights.scm sample.mylang before you build.

injections.scm can mark code inside your language as another installed language. Your language also shows up inside other languages: with the id bash, graphql or cpp, for example, it highlights the matching code blocks in Markdown.