conform.nvim

Lightweight yet powerful formatter plugin for Neovim

<!-- TOC -->

• Requirements
• Features
• Installation
• Setup
• Formatters
• Customizing formatters
  • Magic strings
• Recipes
• Debugging
• Advanced topics
• Options
• Formatter options
• API
  • setup(opts)
  • format(opts, callback)
  • list_formatters(bufnr)
  • list_formatters_to_run(bufnr)
  • list_all_formatters()
  • get_formatter_info(formatter, bufnr)
• FAQ
• Acknowledgements

<!-- /TOC -->

Requirements

• Neovim 0.10+ (for older versions, use a nvim-0.x branch)

Features

• Preserves extmarks and folds - Most formatters replace the entire buffer, which clobbers extmarks and folds, and can cause the viewport and cursor to jump unexpectedly. Conform calculates minimal diffs and applies them using the built-in LSP format utilities.
• Fixes bad-behaving LSP formatters - Some LSP servers are lazy and simply replace the entire buffer, leading to the problems mentioned above. Conform hooks into the LSP handler and turns these responses into proper piecewise changes.
• Enables range formatting for all formatters - Since conform calculates minimal diffs, it can perform range formatting even if the underlying formatter doesn't support it.
• Simple API - Conform exposes a simple, imperative API modeled after vim.lsp.buf.format().
• Formats embedded code blocks - Can format code blocks inside markdown files or similar (see injected language formatting)

Installation

conform.nvim supports all the usual plugin managers

<details> <summary>lazy.nvim</summary>

{
  'stevearc/conform.nvim',
  opts = {},
}

For a more thorough configuration involving lazy-loading, see Lazy loading with lazy.nvim.

</details> <details> <summary>Packer</summary>

require("packer").startup(function()
  use({
    "stevearc/conform.nvim",
    config = function()
      require("conform").setup()
    end,
  })
end)

</details> <details> <summary>Paq</summary>

require("paq")({
  { "stevearc/conform.nvim" },
})

</details> <details> <summary>vim-plug</summary>

Plug 'stevearc/conform.nvim'

</details> <details> <summary>dein</summary>

call dein#add('stevearc/conform.nvim')

</details> <details> <summary>Pathogen</summary>

git clone --depth=1 https://github.com/stevearc/conform.nvim.git ~/.vim/bundle/

</details> <details> <summary>Neovim native package</summary>

git clone --depth=1 https://github.com/stevearc/conform.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/conform/start/conform.nvim

</details>

Setup

At a minimum, you will need to set up some formatters by filetype

require("conform").setup({
  formatters_by_ft = {
    lua = { "stylua" },
    -- Conform will run multiple formatters sequentially
    python = { "isort", "black" },
    -- You can customize some of the format options for the filetype (:help conform.format)
    rust = { "rustfmt", lsp_format = "fallback" },
    -- Conform will run the first available formatter
    javascript = { "prettierd", "prettier", stop_after_first = true },
  },
})

Then you can use conform.format() just like you would vim.lsp.buf.format(). For example, to format on save:

vim.api.nvim_create_autocmd("BufWritePre", {
  pattern = "*",
  callback = function(args)
    require("conform").format({ bufnr = args.buf })
  end,
})

As a shortcut, conform will optionally set up this format-on-save autocmd for you

require("conform").setup({
  format_on_save = {
    -- These options will be passed to conform.format()
    timeout_ms = 500,
    lsp_format = "fallback",
  },
})

See conform.format() for more details about the parameters.

Conform also provides a formatexpr, same as the LSP client:

vim.o.formatexpr = "v:lua.require'conform'.formatexpr()"

To view configured and available formatters, as well as to see the log file, run :ConformInfo

Formatters

You can view this list in vim with :help conform-formatters

<details> <summary>Expand to see all formatters</summary> <!-- FORMATTERS -->

• air - R formatter and language server.
• alejandra - The Uncompromising Nix Code Formatter.
• ansible-lint - ansible-lint with --fix.
• asmfmt - Go Assembler Formatter
• ast-grep - A CLI tool for code structural search, lint and rewriting. Written in Rust.
• astyle - A Free, Fast, and Small Automatic Formatter for C, C++, C++/CLI, Objective-C, C#, and Java Source Code.
• auto_optional - Adds the Optional type-hint to arguments where the default value is None.
• autocorrect - A linter and formatter to help you to improve copywriting, correct spaces, words, and punctuations between CJK.
• autoflake - Removes unused imports and unused variables as reported by pyflakes.
• autopep8 - A tool that automatically formats Python code to conform to the PEP 8 style guide.
• bake - A Makefile formatter and linter.
• bean-format - Reformat Beancount files to right-align all the numbers at the same, minimal column.
• beautysh - A Bash beautifier for the masses.
• bibtex-tidy - Cleaner and Formatter for BibTeX files.
• bicep - Bicep is a Domain Specific Language (DSL) for deploying Azure resources declaratively.
• biome - A toolchain for web projects, aimed to provide functionalities to maintain them. This config runs formatting only. See biome-check or biome-organize-imports for other options.
• biome-check - A toolchain for web projects, aimed to provide functionalities to maintain them. This config runs formatting, linting and import sorting. See biome or biome-organize-imports for other options.
• biome-organize-imports - A toolchain for web projects, aimed to provide functionalities to maintain them. This config runs import sorting only. See biome or biome-check for other options.
• black - The uncompromising Python code formatter.
• blade-formatter - An opinionated blade template formatter for Laravel that respects readability.
• blue - The slightly less uncompromising Python code formatter.
• bpfmt - Android Blueprint file formatter.
• bsfmt - A code formatter for BrighterScript (and BrightScript).
• buf - A new way of working with Protocol Buffers.
• buildifier - buildifier is a tool for formatting bazel BUILD and .bzl files with a standard convention.
• cabal_fmt - Format cabal files with cabal-fmt.
• caramel_fmt - Format Caramel code.
• cbfmt - A tool to format codeblocks inside markdown and org documents.
• cedar - Formats cedar policies.
• clang-format - Tool to format C/C++/… code according to a set of rules and heuristics.
• cljfmt - cljfmt is a tool for detecting and fixing formatting errors in Clojure code.
• cljstyle - Formatter for Clojure code.
• cmake_format - Parse cmake listfiles and format them nicely.
• codeql - Format queries and libraries with CodeQL.
• codespell - Check code for common misspellings.
• commitmsgfmt - Formats commit messages better than fmt(1) and Vim.
• crlfmt - Formatter for CockroachDB's additions to the Go style guide.
• crystal - Format Crystal code.
• csharpier - The opinionated C# code formatter.
• css_beautify - Beautifier for css.
• cue_fmt - Format CUE files using cue fmt command.
• d2 - D2 is a modern diagram scripting language that turns text to diagrams.
• darker - Run black only on changed lines.
• dart_format - Replace the whitespace