💼 neoconf.nvim

neoconf.nvim is a Neovim plugin to manage global and project-local settings.

✨ Features

• configure Neovim using JSON files (can have comments)
  • global settings: ~/.config/nvim/neoconf.json
  • local settings: ~/projects/foobar/.neoconf.json
• live reload of your lsp settings
• import existing settings from vscode, coc.nvim and nlsp-settings.nvim
• auto-completion of all the settings in the Json config files
• auto-completion of all LSP settings in your Neovim Lua config files
• integrates with neodev.nvim. See .neoconf.json in this repo.

⚡️ Requirements

• Neovim >= 0.7.2

📦 Installation

Install the plugin with your preferred package manager:

lazy.nvim

{ "folke/neoconf.nvim" }

🚀 Setup

It's important that you set up neoconf.nvim BEFORE nvim-lspconfig.

require("neoconf").setup({
  -- override any of the default settings here
})

-- setup your lsp servers as usual
require("lspconfig").lua_ls.setup(...)

⚙️ Configuration

neoconf.nvim comes with the following defaults:

{

  -- name of the local settings files
  local_settings = ".neoconf.json",
  -- name of the global settings file in your Neovim config directory
  global_settings = "neoconf.json",
  -- import existing settings from other plugins
  import = {
    vscode = true, -- local .vscode/settings.json
    coc = true, -- global/local coc-settings.json
    nlsp = true, -- global/local nlsp-settings.nvim json settings
  },
  -- send new configuration to lsp clients when changing json settings
  live_reload = true,
  -- set the filetype to jsonc for settings files, so you can use comments
  -- make sure you have the jsonc treesitter parser installed!
  filetype_jsonc = true,
  plugins = {
    -- configures lsp clients with settings in the following order:
    -- - lua settings passed in lspconfig setup
    -- - global json settings
    -- - local json settings
    lspconfig = {
      enabled = true,
    },
    -- configures jsonls to get completion in .nvim.settings.json files
    jsonls = {
      enabled = true,
      -- only show completion in json settings for configured lsp servers
      configured_servers_only = true,
    },
    -- configures lua_ls to get completion of lspconfig server settings
    lua_ls = {
      -- by default, lua_ls annotations are only enabled in your neovim config directory
      enabled_for_neovim_config = true,
      -- explicitly enable adding annotations. Mostly relevant to put in your local .nvim.settings.json file
      enabled = false,
    },
  },

}

🚀 Usage

The :Neoconf Command

• :Neoconf: will show a ui to select one of the local/global json config files to edit
• :Neoconf local: will show a ui to select one of the local json config files to edit
• :Neoconf global: will show a ui to select one of the global json config files to edit
• :Neoconf show: opens a floating window with the merged config
• :Neoconf lsp: opens a floating window with your merged lsp config

Completion and Validation for your Json Settings Files

Completion and Validation for your Lua Settings Files

Completion of your lua settings should work out of the box.

You can additionally use the exported types in other places.

Example with a table containing LSP server settings

  ---@type lspconfig.options
  local servers = {
    ansiblels = {},
    bashls = {},
    clangd = {},
    cssls = {},
    dockerls = {},
    ts_ls = {},
    svelte = {},
    eslint = {},
    html = {},
    jsonls = {
      settings = {
        json = {
          format = {
            enable = true,
          },
          schemas = require("schemastore").json.schemas(),
          validate = { enable = true },
        },
      },
    },
  }

📦 API

Neodev comes with an API that can be used by plugin developers to load global/local settings for their plugin.

---@class SettingsPlugin
---@field name string
---@field setup fun()|nil
---@field on_update fun(event)|nil
---@field on_schema fun(schema: Schema)

-- Registers a plugin. Biggest use-case is to get auto-completion for your plugin in the json settings files
---@param plugin SettingsPlugin
function Neodev.register(plugin) end

---@class WorkspaceOptions
---@field file? string File will be used to determine the root_dir
---@field buffer? buffer Buffer will be used to find the root_dir
---@field lsp? boolean LSP root_dir will be used to determine the root_dir
---@field local? boolean defaults to true. Merge local settings
---@field global? boolean defaults to true. Merge global settings

-- Returns the requested settings
---@generic T : table
---@param key? string Optional key to get settings for
---@param defaults? T Optional table of defaults that will be merged in the result
---@param opts? WorkspaceOptions options to determine the root_dir and what settings to merge
---@return T
function Neoconf.get(key, defaults, opts) end

API Example

-- default config for your plugin
local defaults = {
  doit = true,
  count = 1,
  array = {},
}

-- register your settings schema with Neodev, so auto-completion will work in the json files
require("neoconf.plugins").register({
    on_schema = function(schema)
    -- this call will create a json schema based on the lua types of your default settings
    schema:import("myplugin", defaults)
    -- Optionally update some of the json schema
    schema:set("myplugin.array", {
        description = "Special array containing booleans or numbers",
        anyOf = {
        { type = "boolean" },
        { type = "integer" },
        },
        })
    end,
    })

local my_settings = Neoconf.get("neodev", defaults)

⭐ Acknowledgment

• json.lua a pure-lua JSON library for parsing jsonc files

💻 Supported Language Servers

• als
• astro
• awkls
• basedpyright
• bashls
• clangd
• cssls
• dartls
• denols
• elixirls
• elmls
• eslint
• flow
• fsautocomplete
• grammarly
• haxe_language_server
• hhvm
• hie
• html
• intelephense
• java_language_server
• jdtls
• jsonls
• julials
• kotlin_language_server
• ltex
• lua_ls
• luau_lsp
• omnisharp
• perlls
• perlnavigator
• perlpls
• powershell_es
• psalm
• puppet
• purescriptls
• pylsp
• pyright
• r_language_server
• rescriptls
• rls
• rome
• ruff_lsp
• rust_analyzer
• solargraph
• solidity_ls
• sorbet
• sourcekit
• spectral
• stylelint_lsp
• svelte
• svlangserver
• tailwindcss
• terraformls
• tinymist
• ts_ls
• typst_lsp
• volar
• vtsls
• vuels
• wgls_analyzer
• yamlls
• zeta_note
• zls