Sacro / mason-null-ls.nvim

Table of Contents

• Introduction
  • Star History
• Requirements
• Installation
  • lazy.nvim
  • vim-plug
• Commands
• Configuration
  • Default configuration
• Automatic Setup Usage
  • Example Config
• Handlers usage
• Setup
  • Primary Source of Truth is mason-null-ls
  • Primary Source of Truth is null-ls.
• Available Null-ls sources
  • Auto-resolve logic

mason-null-ls bridges mason.nvim with the null-ls plugin - making it easier to use both plugins together.

Introduction

mason-null-ls.nvim closes some gaps that exist between mason.nvim and null-ls. Its main responsibilities are:

• provide extra convenience APIs such as the :NullLsInstall command
• allow you to (i) automatically install, and (ii) automatically set up a predefined list of sources
• translate between null-ls source names and mason.nvim package names (e.g. haml_lint <-> haml-lint)

It is recommended to use this extension if you use mason.nvim and null-ls. Please read the whole README.md before jumping to Setup.

Note: this plugin uses the null-ls source names in the APIs it exposes - not mason.nvim package names.

Star History

Requirements

• neovim >= 0.7.0
• mason.nvim
• null-ls.nvim

Installation

lazy.nvim

{
    "jay-babu/mason-null-ls.nvim",
    event = { "BufReadPre", "BufNewFile" },
    dependencies = {
      "williamboman/mason.nvim",
      "jose-elias-alvarez/null-ls.nvim",
    },
    config = function()
      require("your.null-ls.config") -- require your null-ls config here (example below)
    end,
}

vim-plug

Plug 'williamboman/mason.nvim'
Plug 'jose-elias-alvarez/null-ls.nvim'
Plug 'jay-babu/mason-null-ls.nvim'

Commands

Available after calling setup.

• :NullLsInstall [<source>...] - installs the provided sources
• :NullLsUninstall <source> ... - uninstalls the provided sources

Configuration

You may optionally configure certain behavior of mason-null-ls.nvim when calling the .setup() function. Refer to the default configuration for a list of all available settings.

Example:

require("mason-null-ls").setup({
    ensure_installed = { "stylua", "jq" }
})

Default configuration

local DEFAULT_SETTINGS = {
    -- A list of sources to install if they're not already installed.
    -- This setting has no relation with the `automatic_installation` setting.
    ensure_installed = {},
    -- Run `require("null-ls").setup`.
    -- Will automatically install masons tools based on selected sources in `null-ls`.
    -- Can also be an exclusion list.
    -- Example: `automatic_installation = { exclude = { "rust_analyzer", "solargraph" } }`
    automatic_installation = false,
    -- See [#handlers-usage](#handlers-usage) section
    handlers = nil,
}

Automatic Setup Usage

Automatic Setup is a need feature that removes the need to configure null-ls for supported sources. Sources found installed in mason will automatically be setup for null-ls.

Example Config

require("mason").setup()
require("mason-null-ls").setup({
    handlers = {},
})

See the Default Configuration section to understand how the default configs can be overridden.

Handlers usage

The handlers table provides a dynamic way of setting up sources and any other needed logic, It can also do that during runtime.

Providing an empty handlers will cause all sources to be automatically registered in null-ls. See below example on how to disable.

local null_ls = require 'null-ls'
null_ls.setup()

require ('mason-null-ls').setup({
    ensure_installed = {'stylua', 'jq'},
    handlers = {
        function() end, -- disables automatic setup of all null-ls sources
        stylua = function(source_name, methods)
          null_ls.register(null_ls.builtins.formatting.stylua)
        end,
        shfmt = function(source_name, methods)
          -- custom logic
          require('mason-null-ls').default_setup(source_name, methods) -- to maintain default behavior
        end,
    },
})

Setup

There are primarily 2 paths to setup.

Primary Source of Truth is mason-null-ls

This involves making sure tools are installed through mason-null-ls when available.

require("mason").setup()
require("mason-null-ls").setup({
    ensure_installed = {
        -- Opt to list sources here, when available in mason.
    },
    automatic_installation = false,
    handlers = {},
})
require("null-ls").setup({
    sources = {
        -- Anything not supported by mason.
    }
})

Note: This is my personal preference.

Primary Source of Truth is null-ls.

require("mason").setup()
require("null-ls").setup({
    sources = {
        -- all sources go here.
    }
})
require("mason-null-ls").setup({
    ensure_installed = nil,
    automatic_installation = true,
})

Available Null-ls sources

Ever since this commit, this plugin attempts to auto-resolve between mason and null-ls. If this is not possible, then there is a way to add exceptions.

Auto-resolve logic

null-ls source name google_java_format, mason-null-ls will attempt to look for an override and if not found, then will attempt to look for a mason named: google-java-format.