Repository files navigation

clojure-ts-mode is an Emacs major mode that provides font-lock (syntaxhighlighting), indentation, and navigation support for theClojure(Script) programming language, powered by thetree-sitter-clojuretree-sitter grammar.

To see a list of available configuration options doM-x customize-group <RET> clojure-ts.

Most configuration changes will require reverting any activeclojure-ts-mode buffers.

clojure-ts-mode currently supports 2 different indentation strategies:

• semantic, the default, which tries to match the indentation ofclojure-mode andcljfmt
• fixed,a simple indentation strategy outlined by Tonsky in a blog post

Set the varclojure-ts-indent-style to change it.

(setq clojure-ts-indent-style'fixed)

Note: You can findthis article comparing semantic and fixed indentation useful.

To highlight entire richcomment expression with the comment font face, set

(setq clojure-ts-comment-macro-font-lock-bodyt)

By default this isnil, so that anything within acomment expression ishighlighted like regular clojure code.

By default markdown syntax is highlighted in the docstrings usingmarkdown_inline grammar. To disable this feature set

(setopt clojure-ts-use-markdown-inlinenil)

To make forms inside of(comment ...) forms appear as top-level forms for evaluation and navigation, set

(setq clojure-ts-toplevel-inside-comment-formt)

To change the maximal line length used byM-x prog-fill-reindent-defun (alsobound toM-q by default) to reformat docstrings and comments it's possible tocustomizeclojure-ts-fill-paragraph variable (by default set to the value ofEmacs'fill-paragraph value).

Every new line in the docstrings is indented byclojure-ts-docstring-fill-prefix-width number of spaces (set to 2 by defaultwhich matches theclojure-mode settings).

clojure-mode has served us wellfor a very long time, but it suffers from a fewlong-standingproblems, related toEmacs limitations baked into its design. The introduction of built-in supportfor Tree-sitter in Emacs 29 provides a natural opportunity to address many ofthem. Enterclojure-ts-mode.

Keep in mind that the transition toclojure-ts-mode won't happen overnight for several reasons:

• getting to feature parity withclojure-mode will take some time
• tools that depend onclojure-mode will need to be updated to work withclojure-ts-mode
• we still need to support users of older Emacs versions that don't support Tree-sitter

That's whyclojure-ts-mode is being developed independently ofclojure-modeand will one day replace it when the time is right. (e.g. 3 major Emacs versiondown the road, so circa Emacs 32)

You can read more about the vision forclojure-ts-modehere.

This library is still under development. Breaking changes should be expected.

This package requires Emacs 29 built with tree-sitter support from theemacs-29 branch.

If you decide to build Emacs from source there's some useful information on this in the Emacs repository:

• Emacs tree-sitter starter-guide
• Emacs install instructions.

To check if your Emacs supports tree sitter run the following (e.g. by usingM-:):

(treesit-available-p)

clojure-ts-mode is available onMElPA andNonGNU ELPA.It can be installed with

(package-install'clojure-ts-mode)

Emacs 29 also includespackage-vc-install, so you can run

(package-vc-install"https://github.com/clojure-emacs/clojure-ts-mode")

to install this package from source.

You can install it by cloning the repository and adding it to your load path.

git clone https://github.com/clojure-emacs/clojure-ts-mode.git

(add-to-list'load-path"~/path/to/clojure-ts-mode/")

Once installed, evaluate clojure-ts-mode.el and you should be ready to go.

The compile tree-sitter clojure shared library must be available to Emacs.Additionally, the tree-sittermarkdown_inline shared librarywill also be used for docstrings if available.

If you havegit and a C compiler (cc) available on your system'sPATH,then these steps should not be necessary. clojure-ts-mode will install thegrammars when you first open a Clojure file andclojure-ts-ensure-grammars isset tot (the default).

If clojure-ts-mode fails to automatically install the grammar, you have the option to install it manually.

Some distributions may package the tree-sitter-clojure grammar in their package repositories.If yours does you may be able to install tree-sitter-clojure with your system package manager.

If the version packaged by your OS is out of date, you may see errors in the*Messages* buffer or your clojure buffers will not have any syntax highlighting.

If this happens you should install the grammar manually withM-x treesit-install-language-grammar <RET> clojure and follow the prompts.Recommended values for these prompts can be seen inclojure-ts-grammar-recipes.

If all else fails, you can attempt to download and compile manually.All you need isgit and a C compiler (GCC works well).

To start, clonetree-sitter-clojure.

Then run the following code (depending on your OS) from the tree-sitter-clojure repository on your machine.

mkdir -p distcc -c -I./src src/parser.c -o"parser.o"cc -fPIC -shared src/parser.o -o"dist/libtree-sitter-clojure.so"

mkdir -p distcc -c -I./src src/parser.c -o"parser.o"cc -fPIC -shared src/parser.o -o"dist/libtree-sitter-clojure.dylib"

I don't know how to do this on Windows. Patches welcome!

Then tell Emacs where to find the shared library by adding something like this to your init file:

(setq treesit-extra-load-path '("~/path/to/tree-sitter-clojure/dist"))

OR you can move thelibtree-sitter-clojure.so/libtree-sitter-clojure.dylib to a directory namedtree-sitterunder youruser-emacs-directory (typically~/.emacs.d on Unix systems).

If you are migrating toclojure-ts-mode note thatclojure-mode is still required for cider and clj-refactor packages to work properly.

After installing the package do the following.

• Check the value ofclojure-mode-hook and copy all relevant hooks toclojure-ts-mode-hook.

(add-hook'clojure-ts-mode-hook#'cider-mode)(add-hook'clojure-ts-mode-hook#'enable-paredit-mode)(add-hook'clojure-ts-mode-hook#'rainbow-delimiters-mode)(add-hook'clojure-ts-mode-hook#'clj-refactor-mode)

• Update.dir-locals.el in all of your Clojure projects to activate directory local variables inclojure-ts-mode.

((clojure-mode  (cider-clojure-cli-aliases.":test:repl")) (clojure-ts-mode  (cider-clojure-cli-aliases.":test:repl")))

Yes! Preliminary support forclojure-ts-mode was released inCIDER1.14. Make sure tograb the latest CIDER from MELPA/GitHub. Note thatclojure-mode is stillneeded for some APIs that haven't yet been ported toclojure-ts-mode.

For now, when you take care of the keybindings for the CIDER commands you useand ensurecider-mode is enabled forclojure-ts-mode buffers in your config,most functionality should already work:

(add-hook'clojure-ts-mode-hook#'cider-mode)

Check outthis article for more details.

Currently, there is anopen PR adding support for inf-clojure.

Copyright © 2022-2025 Danny Freeman andcontributors.

Distributed under the GNU General Public License; typeC-h C-c to view it.