conform.nvim

Lightweight yet powerful formatter plugin for Neovim

• Requirements
• Features
• Installation
• Setup
• Formatters
• Customizing formatters
• 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)
• Acknowledgements

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

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

Customizing formatters

You can override/add to the default values of formatters

require("conform").setup({
  formatters = {
    yamlfix = {
      -- Change where to find the command
      command = "local/path/yamlfix",
      -- Adds environment args to the yamlfix formatter
      env = {
        YAMLFIX_SEQUENCE_STYLE = "block_style",
      },
    },
  },
})

-- These can also be set directly
require("conform").formatters.yamlfix = {
  env = {
    YAMLFIX_SEQUENCE_STYLE = "block_style",
  },
}

-- This can also be a function that returns the config,
-- which can be useful if you're doing lazy loading
require("conform").formatters.yamlfix = function(bufnr)
  return {
    command = require("conform.util").find_executable({
      "local/path/yamlfix",
    }, "yamlfix"),
  }
end

In addition to being able to override any of the original properties on the formatter, there is another property for easily adding additional arguments to the format command

require("conform").formatters.shfmt = {
  prepend_args = { "-i", "2" },
  -- The base args are { "-filename", "$FILENAME" } so the final args will be
  -- { "-i", "2", "-filename", "$FILENAME" }
}
-- prepend_args can be a function, just like args
require("conform").formatters.shfmt = {
  prepend_args = function(self, ctx)
    return { "-i", "2" }
  end,
}

If you want to overwrite the entire formatter definition and not merge with the default values, pass inherit = false. This is also the default behavior if there is no built-in formatter with the given name, which can be used to add your own custom formatters.

require("conform").formatters.shfmt = {
  inherit = false,
  command = "shfmt",
  args = { "-i", "2", "-filename", "$FILENAME" },
}

Recipes

• Format command
• Autoformat with extra features
• Command to toggle format-on-save
• Lazy loading with lazy.nvim
• Leave visual mode after range format
• Run the first available formatter followed by more formatters

Debugging

• Background
• Tools
• Testing the formatter
• Testing vim.system

Advanced topics

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

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
    go = { "goimports", "gofmt" },
    -- You can also customize some of the format options for the filetype
    rust = { "rustfmt", lsp_format = "fallback" },
    -- You can use a function here to determine the formatters dynamically
    python = function(bufnr)
      if require("conform").get_formatter_info("ruff_format", bufnr).available then
        return { "ruff_format" }
      else
        return { "isort", "black" }
      end
    end,
    -- 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" },
  },
  -- Set this to change the default values when calling conform.format()
  -- This will also affect the default values for format_on_save/format_after_save
  default_format_opts = {
    lsp_format = "fallback",
  },
  -- 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_format = "fallback",
    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_format = "fallback",
  },
  -- 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,
  -- Conform will notify you when no formatters are available for the buffer
  notify_no_formatters = true,
  -- Custom formatters and overrides for built-in formatters
  formatters = {
    my_formatter = {
      -- This can be a string or a function that returns a string.
      -- When defining a new formatter, this is the only field that is required
      command = "my_cmd",
      -- A list of strings, or a function that returns a list of strings
      -- Return a single string instead of a list 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(self, 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 stdin=false, use this template to generate the temporary file that gets formatted
      tmpfile_format = ".conform.$RANDOM.$FILENAME",
      -- When returns false, the formatter will not be used
      condition = function(self, 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",
      },
      -- Set to false to disable merging the config with the base definition
      inherit = true,
      -- When inherit = true, add these additional arguments to the beginning of the command.
      -- This can also be a function, like args
      prepend_args = { "--use-tabs" },
      -- When inherit = true, add these additional arguments to the end of the command.
      -- This can also be a function, like args
      append_args = { "--trailing-comma" },
    },
    -- These can also be a function that returns the formatter
    other_formatter = function(bufnr)
      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",
}

Formatter options

• injected
• prettier
• rustfmt
• yew-fmt

API

setup(opts)

setup(opts)

format(opts, callback)

format(opts, callback): boolean \ Format a buffer

Returns:

list_formatters(bufnr)

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

list_formatters_to_run(bufnr)

list_formatters_to_run(bufnr): conform.FormatterInfo[], boolean \ Get the exact formatters that will be run for a buffer.

Returns:

Note:

This accounts for stop_after_first, lsp fallback logic, etc.

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)

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.