BUILTINS.md

Using built-in sources

null-ls includes a library of built-in sources meant to provide out-of-the-box functionality. Built-in sources run with optimizations to reduce startup time and enable user customization.

Loading and registering

null-ls exposes built-ins on null_ls.builtins, which contains the following groups of sources:

-- code action sources
null_ls.builtins.code_actions

-- diagnostic sources
null_ls.builtins.diagnostics

-- formatting sources
null_ls.builtins.formatting

You can then register sources by passing a sources list into your setup function:

local null_ls = require("null-ls")

-- register any number of sources simultaneously
local sources = {
    null_ls.builtins.formatting.prettier,
    null_ls.builtins.diagnostics.write_good,
    null_ls.builtins.code_actions.gitsigns,
}

null_ls.setup {sources = sources}

Built-in sources also have access to a special method, with(), which modifies the source's default options. For example, you can alter a source's file types as follows:

local sources = {
    null_ls.builtins.formatting.prettier.with({
        filetypes = { "html", "json", "yaml", "markdown" },
    }),
}

See the descriptions below or the relevant builtins source file to see the default options passed to each built-in source.

Available Sources

Formatting

StyLua

local sources = {null_ls.builtins.formatting.stylua}

A fast and opinionated Lua formatter written in Rust. Highly recommended!

• Filetypes: { "lua" }
• Command: stylua
• Arguments: { "-" }

LuaFormatter

A flexible but slow Lua formatter. Not recommended for formatting on save.

local sources = {null_ls.builtins.formatting.lua_format}

• Filetypes: { "lua" }
• Command: lua-format
• Arguments: { "-i" }

Prettier

local sources = {null_ls.builtins.formatting.prettier}

• Filetypes: { "javascript", "javascriptreact", "typescript", "typescriptreact", "css", "html", "json", "yaml", "markdown" }
• Command: prettier
• Arguments: { "--stdin-filepath", "$FILENAME" }

prettier_d_slim

A faster version of Prettier that doesn't seem to work well on non-JavaScript filetypes.

local sources = {null_ls.builtins.formatting.prettier_d_slim}

• Filetypes: { "javascript", "javascriptreact", "typescript", "typescriptreact" }
• Command: prettier_d_slim
• Arguments: { "--stdin", "--stdin-filepath", "$FILENAME" }

prettierd

Another "Prettier, but faster" formatter, with better support for non-JavaScript filetypes.

• Filetypes: { "javascript", "javascriptreact", "typescript", "typescriptreact", "css", "html", "json", "yaml", "markdown" }
• Command: prettierd
• Arguments: { "$FILENAME" }

eslint_d

An absurdly fast formatter (and linter). For full integration, check out nvim-lsp-ts-utils.

local sources = {null_ls.builtins.formatting.eslint_d}

• Filetypes: { "javascript", "javascriptreact", "typescript", "typescriptreact" }
• Command: eslint_d
• Arguments: { "--fix-to-stdout", "--stdin", "--stdin-filepath", "$FILENAME" }

trim_whitespace

A simple wrapper around awk to remove trailing whitespace.

local sources = { null_ls.builtins.formatting.trim_whitespace.with({ filetypes = { ... } }) }

• Filetypes: none (must specify in with(), as above)
• Command: awk
• Arguments: { '{ sub(/[ \t]+$/, ""); print }' }

Diagnostics

write-good

English prose linter.

local sources = {null_ls.builtins.diagnostics.write_good}

• Filetypes: { "markdown" }
• Command: write-good
• Arguments: { "--text=$TEXT", "--parse" }

markdownlint via markdownlint-cli

Markdown style and syntax checker.

local sources = {null_ls.builtins.diagnostics.markdownlint}

• Filetypes: { "markdown" }
• Command: markdownlint
• Arguments: { "--stdin" }

tl check via teal

Turns tl check into a linter. It writes the buffer's content to a temporary file, so it works on change, not (only) on save!

Note that Neovim doesn't support Teal files out-of-the-box, so you'll probably want to use vim-teal.

local sources = {null_ls.builtins.diagnostics.teal}

• Filetypes: { "teal" }
• Command: tl
• Arguments: { "check", "$FILENAME" }