clj-refactor.el 4.0

Source: https://metaredux.com/posts/2026/07/16/clj-refactor-4-0.html Hot on the heels ofCIDER 2.0,clj-refactor.el 4.0is out! It’s the first major release of the project in almost five years, and this time around the version bump is not just ceremonial - 4.0 is the biggest batch of user-facing improvements clj-refactor has seen in ages, plus a healthy dose of long-overdue spring cleaning.

Unfinished business

When I announcedclj-refactor.el 3.0back in 2021, I opened with a confession - we had failed to deliver the main objective of that release, namely restoring the dependency hot-loading that JDK 9’s module system broke. Well, better late than never:cljr\-hotload\-dependencyis back in 4.0, reimplemented on top ofclojure\.tools\.deps, and it even acceptsdeps\.edn-style coordinate maps alongside the classic Leiningen vectors.1

I’ll also be honest about the bigger picture, as I was back then: clj-refactor spent most of the intervening years in maintenance mode, whileclojure\-lspbecame the default refactoring engine for much of the community. That hasn’t discouraged me, though - it clarified what clj-refactor should be. The project now has a properroadmapthat spells out where things are headed (spoiler: a static analysis index and closer ties with CIDER), and 4.0 is the first big step in that direction.

The highlights

Thechangelogfor 4.0 has over 40 entries, but here’s what I’m most excited about:

• There’s a newclj\-refactor\-menu- atransientmenu of every command, grouped by category (bound tohhunder your prefix, e.g.C\-c C\-m hh). It mirrors the classic two-letter mnemonics, so it doubles as a way to finally learn them. It replaces the old hydra-powered menus, which allowed us to drop thehydradependency.
• Project-wide refactorings are no longer a leap of faith.cljr\-rename\-symbol,cljr\-change\-function\-signatureandcljr\-inline\-symbolnow show you their edits as a diff and touch nothing until you confirm, and the newcljr\-undo\-last\-refactoring(ur) reverts the last applied refactoring across every affected file in one step.
• The heavyweight commands went asynchronous. Renames, signature changes and file renames used to freeze Emacs while refactor-nrepl analyzed the project - now they return immediately, show a spinner in the mode-line, and finish when the analysis does. Cold-cache runs on big projects are dramatically more pleasant.
• cljr\-change\-function\-signaturegrew up: it can add and remove parameters now (not just reorder and rename them), it understands multi-arity functions, and a long-standing parsing bug that broke it against recent CIDER releases is fixed.
• cljr\-slash(the magic requires feature) learned a neat trick: entries incljr\-magic\-require\-namespacescan carry an:artifactcoordinate, and when the namespace isn’t on your classpath, typingjson/will offer to add the library to your project and hotload it on the spot.
• A bunch of commands now work without a running REPL.cljr\-slashandcljr\-add\-missing\-libspecfall back to the static alias table,cljr\-clean\-nsfalls back to sorting the ns form, andcljr\-remove\-letand the\#\(\.\.\.\)->\(fn \.\.\.\)promotion are handled purely on the Emacs side. Refactoring your requires before the REPL is up is no longer a paper cut.
• Everything got snappier. Artifact lists and libspec suggestions are cached client-side (the latter matters becausecljr\-slashfires on every/keystroke), and the startup cache warming now actually populates the cache the interactive commands read from.
• clj-refactor now talks to refactor-nrepl using namespaced op names (refactor/clean\-nsand friends), with a graceful fallback for older middleware versions. The companionrefactor-nrepl3.14.0 release also hardened the AST analysis and made find-usages noticeably faster on projects with many macros.
• The dependency diet continued:multiple\-cursors,hydraandinflectionsare gone, along with a pile of aliases that had been deprecated since 2.3.0. clj-refactor is a much leaner package than it used to be.
• And a long tail of quality-of-life fixes -cljr\-describe\-refactoringnow opens the wiki page in your browser instead of scraping HTML, the dependency commands give clear errors instead of raw search failures, andclojure\-ts\-modeusers get a working offline ns sort and proper setup docs.

Upgrading

4.0 is a major release and it does come with breaking changes: the minimum requirements are now Emacs 28.1 and CIDER 2.0, the long-deprecated 2.3.0-era command aliases are gone (use theclojure\-\*equivalents that live inclojure\-modethese days), and the legacynamespace\-aliasescode path incljr\-slashwas removed along with its three configuration options. On the middleware side you don’t need to do anything if you usecider\-jack\-in- refactor-nrepl 3.14.0 gets injected automatically, and older versions keep working thanks to the op-name fallback. Most setups should upgrade without touching a thing, but do skim thechangelogif you have a heavily customized configuration.

Five years later

Reading the 3.0 announcement again, I wrote back then that we wanted to show “we haven’t reached the limit of what one can do with a purely (mostly?) REPL-powered approach to refactoring”. I still believe that, and 4.0 is hopefully some evidence. Theroadmaphas the rest of the plan - including making the analysis fast and robust enough to erase the reasons people reach for other tools - and with CIDER 2.0 out the door I finally have some cycles to spend here.

Huge thanks to everyone who contributed to clj-refactor and refactor-nrepl over the years, toClojurists Togetherfor supporting the broader CIDER ecosystem, and to everyone who kept filing issues during the quiet years - they shaped most of what shipped in this release.

In the REPL we trust!