Skip to content

Prelude Apheleia

Overview

Apheleia is a unified format-on-save framework for Emacs. On save, it runs the appropriate external formatter (Prettier, Black, Ruff, gofmt, rustfmt, ...) asynchronously, then patches the buffer with the result. The patching is point-preserving and flicker-free -- it feels like the formatter ran instantly with no visible buffer churn.

Apheleia ships with sensible defaults for dozens of formatters and many major modes out of the box. Look at apheleia-formatters and apheleia-mode-alist for the full list.

What this module does

Just two things:

  1. Installs the apheleia package.
  2. Enables apheleia-global-mode.

That's it -- no further setup required for the languages Apheleia already knows about.

Relationship to language modules

Several Prelude language modules install their own format-on-save hooks (e.g. rust-format-on-save in prelude-rust, gofmt-before-save in prelude-go). These keep working with Apheleia enabled -- they just run redundantly. If you enable this module you can safely drop them from your personal config, or disable them with hooks like:

(with-eval-after-load 'rust-ts-mode
  (setq rust-format-on-save nil))

(with-eval-after-load 'go-mode
  (remove-hook 'before-save-hook 'gofmt-before-save))

Adding a formatter

For languages or tools Apheleia doesn't know about, register a formatter and tell Apheleia which mode it applies to:

(with-eval-after-load 'apheleia
  (setf (alist-get 'shfmt apheleia-formatters)
        '("shfmt" "-i" "2" "-ci"))
  (setf (alist-get 'sh-mode apheleia-mode-alist) 'shfmt))

See the Apheleia README for the formatter spec and built-in entries you can copy from.

Disabling per buffer

If you need to skip formatting for a specific buffer, run M-x apheleia-mode to toggle it off locally. To skip a whole project, set a directory-local apheleia-inhibit to t.