⚙️ codesettings.nvim

Easily read your project's local settings files and merge them into your Neovim 0.11+ native LSP configuration.

This plugin makes it easy to reuse settings your team already committed to version control for VS Code by providing an API to merge the relevant settings from VS Code's settings schema into the LSP settings table you pass to vim.lsp.config() (or any way you configure LSP).

Requirements

• Neovim 0.11+ (uses the new vim.lsp.config() API)
• A JSON(C) file in your project root with LSP settings (optional; if missing, your config is returned unchanged). Paths are configurable, but by default, the plugin looks for any of:
  • .vscode/settings.json
  • codesettings.json
  • lspsettings.json

Installation

For some features (namely, jsonls integration and jsonc filetype handling), you must call setup().

• lazy.nvim (recommended)

return {
  'mrjones2014/codesettings.nvim',
  -- these are the default settings just set `opts = {}` to use defaults
  opts = {
    ---Look for these config files
    config_file_paths = { '.vscode/settings.json', 'codesettings.json', 'lspsettings.json' },
    ---Integrate with jsonls to provide LSP completion for LSP settings based on schemas
    jsonls_integration = true,
    ---Set up library paths for lua_ls automatically to pick up the generated type
    ---annotations provided by codesettings.nvim; to enable for only your nvim config,
    ---you can also do something like:
    ---lua_ls_integration = function()
    ---  return vim.uv.cwd() == ('%s/.config/nvim'):format(vim.env.HOME)
    ---end,
    lua_ls_integration = true,
    ---Set filetype to jsonc when opening a file specified by `config_file_paths`,
    ---make sure you have the jsonc tree-sitter parser installed for highlighting
    jsonc_filetype = true,
    ---Provide your own root dir; can be a string or function returning a string.
    ---It should be/return the full absolute path to the root directory.
    ---If not set, defaults to `require('codesettings.util').get_root()`
    root_dir = nil,
    ---Choose the default merge behavior
    merge_opts = {
      --- How to merge lists; 'append' (default), 'prepend' or 'replace'
      list_behavior = 'append',
    },
  },
  -- I recommend loading on these filetype so that the
  -- jsonls integration, lua_ls integration, and jsonc filetype setup works
  ft = { 'json', 'jsonc', 'lua' },
}

Quick start

Recommended setup: If you don't use before_init for anything else, you can use it as a global hook to look for local config files for all LSPs:

vim.lsp.config('*', {
  before_init = function(_, config)
    local codesettings = require('codesettings')
    config = codesettings.with_local_settings(config.name, config)
  end,
})

Alternatively, you can configure it on a per-server basis.

-- you can also still use `before_init` here
-- if you want codesettings to be `require`d
-- lazily
local codesettings = require('codesettings')
vim.lsp.config(
  'yamlls',
  codesettings.with_local_settings('yamlls', {
    settings = {
      yaml = {
        validate = true,
        schemaStore = { enable = true },
      },
    },
  }, {
    -- you can also pass custom merge opts on a per-server basis
    list_behavior = 'replace',
  })
)

-- or from a config file under `/lsp/rust-analyzer.lua` in your config directory.
-- if you use rustaceanvim to configure rust-analyzer, see the `rustaceanvim` section below
return codesettings.with_local_settings('rust-analyzer', {
  settings = {
    -- ...
  },
})

Rustaceanvim

The before_init global hook does not work if you use rustaceanvim to configure rust-analyzer, however you can still use codesettings.nvim to merge local settings.

rustaceanvim loads VS Code settings by default, but your global settings override the local ones; codesettings.nvim does the opposite. Here's how I configure rustaceanvim in my own setup:

return {
  'mrcjkb/rustaceanvim',
  ft = 'rust',
  version = '^6',
  dependencies = { 'mrjones2014/codesettings.nvim' },
  init = function()
    vim.g.rustaceanvim = {
      -- the rest of your settings go here...

      -- I want VS Code settings to override my settings,
      -- not the other way around, so use codesettings.nvim
      -- instead of rustaceanvim's built-in vscode settings loader
      load_vscode_settings = false,
      -- the global hook doesn't work when configuring rust-analyzer with rustaceanvim
      settings = function(_, config)
        return require('codesettings').with_local_settings('rust-analyzer', config)
      end,
      default_settings = {
        ['rust-analyzer'] = {
          -- your global LSP settings go here
        },
      },
    }
  end,
}

Features

• Minimal API: one function you call per server setup, or with a global hook (see example above)
• jsonc filetype for local config files
• jsonls integration for schema-based completion of LSP settings in JSON(C) configuration files
• Lua type annotations generated from schemas for autocomplete when writing LSP configs in Lua, with optional lua_ls integration
• Supports custom config file names/locations
• Custom one-shot loaders with configuration that differs from the plugin's global config (see Advanced Usage)
• Supports mixed nested and dotted key paths, for example, this project's codesettings.json looks like:

{
  "Lua": {
    "runtime.version": "LuaJIT",
    "workspace": {
      "library": ["${3rd}/luassert/library", "${addons}/busted/library"],
      "checkThirdParty": false,
    },
    "diagnostics.globals": ["vim", "setup", "teardown"],
  },
}

To get autocomplete in Lua files, either set config.lua_ls_integration = true, or use ---@module 'codesettings' which will tell lua_ls as though codesettings has been required, then you will have access to ---@type lsp.server_name generated type annotations.

-- for example, for lua_ls
vim.lsp.config('lua_ls', {
  -- this '@module' annotation makes lua_ls import the library from codesettings,
  -- where the annotations come from; this isn't needed if you use `lua_ls_integration = true`
  -- and `codesettings.nvim` is loaded
  ---@module 'codesettings'
  -- then you will have access to the generated type annotations
  ---@type lsp.lua_ls
  settings = {},
})

Commands

• :Codesettings show - show the resolved LSP config for each active LSP client; note that this only shows active clients
• :Codesettings local - show the resolved local config found in local config files in your project
• :Codesettings files - show the config files found in your project
• :Codesettings edit - edit or create a local config file based on your configured config file paths
• :Codesettings health - check plugin health (alias for :checkhealth codesettings)

API

• require('codesettings').setup(opts?: CodesettingsConfig)

  • Initialize the plugin. You only need to call this for jsonls_integration and jsonc_filetype to work, or to customize the local filepaths to look for. It is not required for your local configs to take effect, unless you wish to use non-default plugin configuration.

• require('codesettings').with_local_settings(lsp_name: string, config: table, opts: CodesettingsConfigOverrides?): table

  • Loads settings from the configured files, extracts relevant settings for the given LSP based on its schema, and deep-merges into config.settings. Returns the merged config.

• require('codesettings').local_settings(opts: CodesettingsConfigOverrides?): Settings

  • Loads and parses the settings file(s) for the current project. Returns a Settings object.
  • Settings object provides some methods like:
    • Settings:schema(lsp_name) - Filter the settings down to only the keys that match the relevant schema e.g. settings:schema('eslint')
    • Settings:merge(settings, key, merge_opts) - merge another Settings object into this one, optionally specify a sub-key to merge, and control merge behavior with the 2nd and 3rd parameter, respectively
    • Settings:get(key) - returns the value at the specified key; supports dot-separated key paths like Settings:get('some.sub.property')
    • Settings:get_subtable(key) - like Settings:get(key), but returns a Settings object if the path is a table, otherwise nil
    • Settings:clear() - remove all values
    • Settings:set(key, value) - supports dot-separated key paths like some.sub.property

Example using local_settings() directly:

local codesettings = require('codesettings')
local eslint_settings = c.local_settings()
  :schema('eslint')
  :merge({
    eslint = {
      codeAction = {
        disableRuleComment = {
          enable = true,
          location = 'sameLine',
        },
      },
    },
  })
  :get('eslint.codeAction') -- get the codeAction subtable

How it finds your settings

• Root discovery uses vim.fs.root to search upwards with markers based on your configured config file paths, as well as .git and .jj (for Jujutsu repos)
• The plugin checks each path in config_file_paths under your project root and uses any that exist

How merging works

Follows the semantics of vim.tbl_deep_extend('force', your_config, local_config), essentially:

• The plugin deep-merges plain tables (non-list tables)
• List/array values are appended by default; you can change this behavior in configuration or through the API
• Your provided config is the base; values from the settings file override or extend it within config.settings

Advanced Usage

One-shot Loaders

codesettings.nvim provides a fluent ConfigBuilder API that lets you override plugin options for a single load of local settings, without affecting the global configuration. This is useful, for example, for multi-root projects where you might have a separate instance of the LSP server per-root.

vim.lsp.config('rust_analyzer', {
  before_init = function(_, config)
    local c = require('codesettings')
    c
      -- starts from the plugin's global config as a base
      .loader()
      -- override the root directory from the LSP config, which might be a sub-root
      :root_dir(config.root_dir)
      -- merge local settings according to the configuration specified
      -- by this `ConfigBuilder`
      :with_local_settings(
        config.name,
        config
      )
  end,
})

See codesettings.config.builder for the full available API and which settings can be overridden.

Loader Extensions

codesettings.nvim allows for custom post-processing of your local config files. Extensions can be registered globally, or through the ConfigBuilder for one-shot loaders. Extensions can be registered directly, or via a string which will be required. No extensions are registered by default.

local SomeExtension = require('some-3rdparty-extension')
require('codesettings').setup({
  loader_extensions = { SomeExtension, 'another-3rdparty-extension' },
})

-- or for one-shot loaders
require('codesettings')
  .loader()
  :loader_extensions({ SomeExtension, 'another-3rdparty-extension' })
  :with_local_settings('lua_ls', {
    -- ...
  })

codesettings.nvim supplies one built-in extension that can expand environment variables in your config files. It supports $ENV_VAR, ${ENV_VAR}, and even ${ENV_VAR:-/some/default/path} syntax. It can be registered via the codesettings.extensions.env module path.

Extension API

The extension API expects extensions to be modules that provide at least one of two API functions. The types that describe an extension are:

---@class CodesettingsLoaderExtensionContext
---@field parent table? The immediate parent table/list of this node
---@field path string[] Full path from the root to this node
---@field key string|integer The key/index of this node in the parent
---@field list_idx integer? Index if parent is a list

---@class CodesettingsLoaderExtension
---Optional visitor for non-leaf nodes (tables or lists). Return a control code and optional replacement value.
---Note that the replacement value is only used if the control code is `REPLACE`.
---@field object (fun(node:any, ctx:CodesettingsLoaderExtensionContext): CodesettingsLoaderExtensionControl, any?)?
---Optional visitor for leaf nodes. Return a control code and optional replacement value.
---Note that the replacement value is only used if the control code is `REPLACE`.
---@field leaf (fun(value:any, ctx:CodesettingsLoaderExtensionContext): CodesettingsLoaderExtensionControl, any?)?

---@enum CodesettingsLoaderExtensionControl
M.Control = {
  ---Continue recursion (for objects) or leave leaf unchanged
  CONTINUE = 'continue',
  ---Skip recursion (objects only)
  SKIP = 'skip',
  ---Replace this node/leaf with provided replacement value (can be nil)
  REPLACE = 'replace',
}

Extensions support both simple table style extensions, as well as stateful method style extensions; they will work whether your functions need to be called like extension.leaf(value, ctx) or extension:leaf(value, ctx).

See codesettings.extensions.env for a simple example extension.

Comparison with neoconf.nvim

	codesettings.nvim	neoconf.nvim
Minimum Neovim version	Neovim >= 0.11.0	Neovim >= 0.7.2
Depends on nvim-lspconfig	No (but will still work with it if you choose to use it)	Yes
Supports mixed nested and dotted key paths	Yes	No
Customizable list value merging behavior	Yes	No
jsonls integration	Yes, including mixed nested and dotted key paths	Yes
jsonc filetype support	Yes	Yes
setup() required	Only for some editor integration features	Yes
Loading settings	API call	Automatic through nvim-lspconfig hooks

The tl;dr: is if you wish to use nvim-lspconfig, then neoconf.nvim is more automatic but provides fewer features, supports fewer LSP servers, and seems to be unmaintained. If you want to get rid of nvim-lspconfig and just use vim.lsp.config() APIs, then codesettings.nvim provides an API to load local project settings for you, as well as better autocomplete in configuration files, and autocomplete in Lua files not using nvim-lspconfig based on Lua type annotations.

Acknowledgements

This project would not exist without the hard work of some other open source projects!

• Some parts of this plugin are based on folke's neoconf.nvim plugin
• This plugin bundles json.lua, a pure-Lua JSON library for parsing jsonc files

Supported LSP Servers

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