conform.nvim

Lightweight yet powerful formatter plugin for Neovim

• Requirements
• Features
• Installation
• Setup
• Formatters
• Options
• Recipes
• Advanced topics
• API
  • format(opts, callback)
  • list_formatters(bufnr)
  • list_all_formatters()
  • get_formatter_info(formatter, bufnr)
  • will_fallback_lsp(options)
• Acknowledgements

Requirements

• Neovim 0.8+

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 - Use the injected formatter to format code blocks e.g. in markdown files.

Installation

conform.nvim supports all the usual plugin managers

lazy.nvim

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

Packer

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

Paq

require "paq" {
    {'stevearc/conform.nvim'};
}

vim-plug

Plug 'stevearc/conform.nvim'

dein

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

Pathogen

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

Neovim native package

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

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" },
        -- Use a sub-list to run only the first available formatter
        javascript = { { "prettierd", "prettier" } },
    },
})

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_fallback = true,
    },
})

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

• alejandra - The Uncompromising Nix Code Formatter.
• astyle - A Free, Fast, and Small Automatic Formatter for C, C++, C++/CLI, Objective-C, C#, and Java Source Code.
• 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.
• beautysh - A Bash beautifier for the masses.
• bibtex-tidy - Cleaner and Formatter for BibTeX files.
• biome - A toolchain for web projects, aimed to provide functionalities to maintain them.
• black - The uncompromising Python code formatter.
• buf - A new way of working with Protocol Buffers.
• clang_format - Tool to format C/C++/… code according to a set of rules and heuristics.
• cljstyle - Formatter for Clojure code.
• cmake_format - Parse cmake listfiles and format them nicely.
• codespell - Check code for common misspellings.
• darker - Run black only on changed lines.
• dart_format - Replace the whitespace in your program with formatting that follows Dart guidelines.
• deno_fmt - Use Deno to format TypeScript, JavaScript/JSON and markdown.
• dfmt - Formatter for D source code.
• djlint - ✨ HTML Template Linter and Formatter. Django - Jinja - Nunjucks - Handlebars - GoLang.
• dprint - Pluggable and configurable code formatting platform written in Rust.
• easy-coding-standard - ecs - Use Coding Standard with 0-knowledge of PHP-CS-Fixer and PHP_CodeSniffer.
• elm_format - elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide.
• erb_format - Format ERB files with speed and precision.
• eslint_d - Like ESLint, but faster.
• fish_indent - Indent or otherwise prettify a piece of fish code.
• fixjson - JSON Fixer for Humans using (relaxed) JSON5.
• gci - GCI, a tool that controls Go package import order and makes it always deterministic.
• gdformat - A formatter for Godot's gdscript.
• gofmt - Formats go programs.
• gofumpt - Enforce a stricter format than gofmt, while being backwards compatible. That is, gofumpt is happy with a subset of the formats that gofmt is happy with.
• goimports - Updates your Go import lines, adding missing ones and removing unreferenced ones.
• golines - A golang formatter that fixes long lines.
• google-java-format - Reformats Java source code according to Google Java Style.
• htmlbeautifier - A normaliser/beautifier for HTML that also understands embedded Ruby. Ideal for tidying up Rails templates.
• indent - GNU Indent.
• injected - Format treesitter injected languages.
• isort - Python utility / library to sort imports alphabetically and automatically separate them into sections and by type.
• jq - Command-line JSON processor.
• just - Format Justfile.
• latexindent - A perl script for formatting LaTeX files that is generally included in major TeX distributions.
• markdown-toc - API and CLI for generating a markdown TOC (table of contents) for a README or any markdown files.
• markdownlint - A Node.js style checker and lint tool for Markdown/CommonMark files.
• mdformat - An opinionated Markdown formatter.
• mix - Format Elixir files using the mix format command.
• nixfmt - nixfmt is a formatter for Nix code, intended to apply a uniform style.
• nixpkgs_fmt - nixpkgs-fmt is a Nix code formatter for nixpkgs.
• ocamlformat - Auto-formatter for OCaml code.
• perlimports - Make implicit Perl imports explicit.
• perltidy - Perl::Tidy, a source code formatter for Perl.
• pg_format - PostgreSQL SQL syntax beautifier.
• php_cs_fixer - The PHP Coding Standards Fixer.
• phpcbf - PHP Code Beautifier and Fixer fixes violations of a defined coding standard.
• prettier - Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.
• prettierd - prettier, as a daemon, for ludicrous formatting speed.
• rubocop - Ruby static code analyzer and formatter, based on the community Ruby style guide.
• ruff_fix - An extremely fast Python linter, written in Rust. Fix lint errors.
• ruff_format - An extremely fast Python linter, written in Rust. Formatter subcommand.
• rustfmt - A tool for formatting rust code according to style guidelines.
• rustywind - A tool for formatting Tailwind CSS classes.
• scalafmt - Code formatter for Scala.
• shellcheck - A static analysis tool for shell scripts.
• shellharden - The corrective bash syntax highlighter.
• shfmt - A shell parser, formatter, and interpreter with bash support.
• sql_formatter - A whitespace formatter for different query languages.
• squeeze_blanks - Squeeze repeated blank lines into a single blank line via cat -s.
• standardjs - JavaScript Standard style guide, linter, and formatter.
• standardrb - Ruby's bikeshed-proof linter and formatter.
• stylelint - A mighty CSS linter that helps you avoid errors and enforce conventions.
• stylua - An opinionated code formatter for Lua.
• swift_format - Swift formatter from apple. Requires building from source with swift build.
• swiftformat - SwiftFormat is a code library and command-line tool for reformatting swift code on macOS or Linux.
• taplo - A TOML toolkit written in Rust.
• templ - Formats templ template files.
• terraform_fmt - The terraform-fmt command rewrites terraform configuration files to a canonical format and style.
• trim_newlines - Trim new lines with awk.
• trim_whitespace - Trim whitespaces with awk.
• uncrustify - A source code beautifier for C, C++, C#, ObjectiveC, D, Java, Pawn and Vala.
• xmlformat - xmlformatter is an Open Source Python package, which provides formatting of XML documents.
• yamlfix - A configurable YAML formatter that keeps comments.
• yamlfmt - yamlfmt is an extensible command line tool or library to format yaml files.
• yapf - Yet Another Python Formatter.
• zigfmt - Reformat Zig source into canonical form.

Options

A complete list of all configuration options

require("conform").setup({
  -- Map of filetype to formatters
  formatters_by_ft = {
    lua = { "stylua" },
    -- Conform will run multiple formatters sequentially
    python = { "isort", "black" },
    -- Use a sub-list to run only the first available formatter
    javascript = { { "prettierd", "prettier" } },
    -- Use the "*" filetype to run formatters on all filetypes.
    ["*"] = { "codespell" },
    -- Use the "_" filetype to run formatters on filetypes that don't
    -- have other formatters configured.
    ["_"] = { "trim_whitespace" },
  },
  -- If this is set, Conform will run the formatter on save.
  -- It will pass the table to conform.format().
  -- This can also be a function that returns the table.
  format_on_save = {
    -- I recommend these options. See :help conform.format for details.
    lsp_fallback = true,
    timeout_ms = 500,
  },
  -- If this is set, Conform will run the formatter asynchronously after save.
  -- It will pass the table to conform.format().
  -- This can also be a function that returns the table.
  format_after_save = {
    lsp_fallback = true,
  },
  -- Set the log level. Use `:ConformInfo` to see the location of the log file.
  log_level = vim.log.levels.ERROR,
  -- Conform will notify you when a formatter errors
  notify_on_error = true,
  -- Define custom formatters here
  formatters = {
    my_formatter = {
      -- This can be a string or a function that returns a string
      command = "my_cmd",
      -- OPTIONAL - all fields below this are optional
      -- A list of strings, or a function that returns a list of strings
      -- Return a single string instead to run the command in a shell
      args = { "--stdin-from-filename", "$FILENAME" },
      -- If the formatter supports range formatting, create the range arguments here
      range_args = function(ctx)
        return { "--line-start", ctx.range.start[1], "--line-end", ctx.range["end"][1] }
      end,
      -- Send file contents to stdin, read new contents from stdout (default true)
      -- When false, will create a temp file (will appear in "$FILENAME" args). The temp
      -- file is assumed to be modified in-place by the format command.
      stdin = true,
      -- A function that calculates the directory to run the command in
      cwd = require("conform.util").root_file({ ".editorconfig", "package.json" }),
      -- When cwd is not found, don't run the formatter (default false)
      require_cwd = true,
      -- When returns false, the formatter will not be used
      condition = function(ctx)
        return vim.fs.basename(ctx.filename) ~= "README.md"
      end,
      -- Exit codes that indicate success (default {0})
      exit_codes = { 0, 1 },
      -- Environment variables. This can also be a function that returns a table.
      env = {
        VAR = "value",
      },
    },
    -- These can also be a function that returns the formatter
    other_formatter = function()
      return {
        command = "my_cmd",
      }
    end,
  },
})

-- You can set formatters_by_ft and formatters directly
require("conform").formatters_by_ft.lua = { "stylua" }
require("conform").formatters.my_formatter = {
  command = "my_cmd",
}

Recipes

• Format command
• Customizing formatters
• Autoformat with extra features
• Command to toggle format-on-save
• Automatically run slow formatters async
• Add extra arguments to a formatter command
• Lazy loading with lazy.nvim

Advanced topics

• Minimal format diffs
• Range formatting
• Injected language formatting (code blocks)

API

format(opts, callback)

format(opts, callback): boolean
Format a buffer

Param	Type	Desc
opts	nil|table
	timeout_ms	nil|integer	Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true.
	bufnr	nil|integer	Format this buffer (default 0)
	async	nil|boolean	If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded.
	formatters	nil|string[]	List of formatters to run. Defaults to all formatters for the buffer filetype.
	lsp_fallback	nil|boolean|"always"	Attempt LSP formatting if no formatters are available. Defaults to false. If "always", will attempt LSP formatting even if formatters are available.
	quiet	nil|boolean	Don't show any notifications for warnings or failures. Defaults to false.
	range	nil|table	Range to format. Table must contain start and end keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode
	id	nil|integer	Passed to vim.lsp.buf.format when lsp_fallback = true
	name	nil|string	Passed to vim.lsp.buf.format when lsp_fallback = true
	filter	nil|fun(client: table): boolean	Passed to vim.lsp.buf.format when lsp_fallback = true
callback	nil|fun(err: nil|string)	Called once formatting has completed

Returns:

Type	Desc
boolean	True if any formatters were attempted

list_formatters(bufnr)

list_formatters(bufnr): conform.FormatterInfo[]
Retrieve the available formatters for a buffer

Param	Type	Desc
bufnr	nil|integer

list_all_formatters()

list_all_formatters(): conform.FormatterInfo[]
List information about all filetype-configured formatters

get_formatter_info(formatter, bufnr)

get_formatter_info(formatter, bufnr): conform.FormatterInfo
Get information about a formatter (including availability)

Param	Type	Desc
formatter	string	The name of the formatter
bufnr	nil|integer

will_fallback_lsp(options)

will_fallback_lsp(options): boolean
Check if the buffer will use LSP formatting when lsp_fallback = true

Param	Type	Desc
options	nil|table	Options passed to vim.lsp.buf.format

Acknowledgements

Thanks to

• nvim-lint for providing inspiration for the config and API. It's an excellent plugin that balances power and simplicity.
• null-ls for formatter configurations and being my formatter/linter of choice for a long time.