Using clojure-ts-mode

clojure-ts-mode is a tree-sitter-powered major mode for editing Clojure, and the eventual successor to the classic clojure-mode. CIDER works with it, so you can pair CIDER’s interactive-programming features with a tree-sitter editing experience.

clojure-ts-mode support was introduced in CIDER 1.14.

Enabling cider-mode

Just as with clojure-mode, CIDER’s minor mode isn’t forced on you - enable it by adding it to the mode hook:

(add-hook 'clojure-ts-mode-hook #'cider-mode)
There’s no need to enable it explicitly for modes derived from clojure-ts-mode (such as clojure-ts-clojurescript-mode) - those inherit the hook.

Once cider-mode is on, the usual commands are available and the CIDER menu and keybindings are installed in clojure-ts-mode buffers. Starting a REPL works the same way too: visit a project file and run M-x cider-jack-in (see Quick Start).

Current state and limitations

CIDER has solid, but still-evolving, support for clojure-ts-mode. Most of what CIDER does in a buffer now works natively with tree-sitter:

  • dynamic syntax highlighting of REPL-defined macros, functions and vars, including the markers for deprecated, instrumented and traced symbols

  • highlighting of the #break, #dbg and #light debugging reader tags

  • CIDER’s own Clojure buffers (macroexpansions, evaluation results, tracing output and the like), which open in clojure-ts-mode when that’s your preferred mode (see below)

The important thing to know is that CIDER still depends on clojure-mode for some of its work - notably for extracting information about the Clojure code in a buffer. So even when you edit with clojure-ts-mode, you should keep clojure-mode installed (it’s a hard dependency of CIDER anyway, so it will be).

The long-term plan is to make clojure-ts-mode capable of providing CIDER with everything it needs directly, at which point the clojure-mode dependency for buffer analysis will fall away. That work is ongoing and will take some time, so if you hit a rough edge with clojure-ts-mode that clojure-mode handles smoothly, that mismatch is the usual cause.

If you’re deciding whether to switch, clojure-ts-mode’s own README tracks its maturity and feature coverage. CIDER will keep supporting `clojure-mode for the foreseeable future, so there’s no rush.

Choosing the mode CIDER renders Clojure with

Besides the buffers you edit, CIDER produces a fair amount of Clojure of its own: REPL input and results, examples in documentation buffers, debugger and enlighten overlays, xref labels, and the display buffers for macroexpansion, evaluation results and tracing. cider-preferred-clojure-mode controls which major mode font-locks all of that:

  • auto (the default) picks clojure-ts-mode when your Clojure source files open in it and its tree-sitter grammar is ready, and clojure-mode otherwise.

  • clojure-mode always uses clojure-mode.

  • clojure-ts-mode uses clojure-ts-mode when it’s available and falls back to clojure-mode when it isn’t.

The default follows your editing setup, so you rarely need to touch it. Set it explicitly if, say, you edit with clojure-ts-mode but prefer the classic highlighting in the REPL:

(setq cider-preferred-clojure-mode 'clojure-mode)