nx.nvim

Utility library to n^x your work with the nvim api.

Features

Keymaps
Highlights
Autocommands
Commands

Installation

Getting Started

Features

All features maintain familiarity with their underlying base functions. Below is an overview of their differences and extended functionalities.

nx.map

Based on vim.keymap.set()

vim.keymap.set('n', ';w', "<Cmd>w<CR>")
vim.keymap.set('n', ';q', "<Cmd>w<CR>", { desc = "Close Current Window" })
vim.keymap.set('', "j", "&wrap ? 'gj' : 'j'", { expr = true, silent = true })
vim.keymap.set('', "<Down>", "&wrap ? 'gj' : 'j'", { expr = true, silent = true })

-- Can be written as
nx.map({
   { ";w", "<Cmd>w<CR>" },
   { ";q", "<Cmd>confirm quit<CR>", desc = "Close Current Window" },
   { { "j", "<Down>" }, "&wrap ? 'gj' : 'j'", "", expr = true, silent = true },
})

-- Options like filetype and wk_label are not directly supported by vim.keymap.set
nx.map({
   { "<leader>ts", "<Cmd>set spell!<CR>", desc = "Toggle Spellcheck", wk_label = "Spellcheck" },
   { "<leader>tp", "<Cmd>MarkdownPreviewToggle<CR>", ft = "markdown", desc = "Toggle Markdown Preview" },
})
-- Wrapper options
nx.map({
   -- Line Navigation
   { { "j", "<Down>" }, "&wrap ? 'gj' : 'j'", "" },
   { { "k", "<Up>" }, "&wrap ? 'gk' : 'k'", "" },
   { "$", "&wrap ? 'g$' : '$'", "" },
   { "^", "&wrap ? 'g^' : '^'", "" },
   -- Enter insert mode at indentation level on empty lines
   { "i", "len(getline('.')) == 0 ? '\"_cc' : 'i'"  },
   }, { expr = true, silent = true })
})

Differences

Map single or multiple keymaps
The only required values are index [1]: lhs and [2]: rhs
mode: defaults to "n" and instead of being passed as index [1] it is optional as [3] or mode key
opts: are passed inline instead of in a separate table
- additional options:
  - wk_label: to create which-key labels that should differ from the key's description
  - ft: to create filetype specific mappings
- {<wrapper_opts>}: to add options to all keymaps within a nx.map()

Detailed Examples _{^{Toggle visibility...}}

Feature overview

nx.map({ ";q", "<Cmd>confirm quit<CR>", desc = "Close Current Window" })
---@ ╰── set a single keymap
---@ ╭── or lists of keymaps
nx.map({
   -- Line Navigation
   ---@    ╭── multiple lhs
   { { "j", "<Up>" }, "&wrap ? 'gj' : 'j'", "" },
   { { "k", "<Down>" }, "&wrap ? 'gk' : 'k'", "" },
   { "$", "&wrap ? 'g$' : '$'", "" },
   { "^", "&wrap ? 'g^' : '^'", "" },
   -- Indentation
   { "i", function() return smart_indent "i" end },
   { "a", function() return smart_indent "a" end },
   { "A", function() return smart_indent "A" end },
   }, { expr = true, silent = true })
---@      ╰── wrapper opts apply options to all entries

nx.map({
   { "<Esc>", "<Esc>", "i" },
   { "<C-c>", "<Cmd>close<CR>", { "i", "x" } },
   { "q", "<Cmd>close<CR>", "x" },
   ---@ set filetype keymaps ──╮ (in {wrapper_opts} or for single keymaps)
}, { buffer = 0, ft = "DressingInput" })

Mode

Specify a mode|mode[] other than "n" as index [3] or mode key (inline or in wrapper_opts).

nx.map({
{ "<kEnter>", "<CR>", { "", "!" }, desc = "Enter" }
---@ ^=                      ╰── or  ──╮
{ "<kEnter>", "<CR>", desc = "Enter", mode = { "", "!" } }
}, { mode = { "", "!" }) -- or in wrapper_opts (here it has to be the `mode` key)

Wrapper options

Add options to all entries in a list of keymaps - inline keymap options are treated with higher priority and won't be overwritten by wrapper options. As an example, let's compare nx.map for setting neovim/nvim-lspconfig#suggested-configuration.

---@ reference using the default vim.keymap.set

local opts = { noremap=true, silent=true }
vim.keymap.set('n', '<space>e', vim.diagnostic.open_float, opts)
vim.keymap.set('n', '[d', vim.diagnostic.goto_prev, opts)
vim.keymap.set('n', ']d', vim.diagnostic.goto_next, opts)
vim.keymap.set('n', '<space>q', vim.diagnostic.setloclist, opts)

local on_attach = function(client, bufnr)
   local bufopts = { noremap=true, silent=true, buffer=bufnr }
   vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, bufopts)
   vim.keymap.set('n', 'gd', vim.lsp.buf.definition, bufopts)
   vim.keymap.set('n', 'K', vim.lsp.buf.hover, bufopts)
   vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, bufopts)
   vim.keymap.set('n', '<C-k>', vim.lsp.buf.signature_help, bufopts)
   vim.keymap.set('n', '<space>wa', vim.lsp.buf.add_workspace_folder, bufopts)
   vim.keymap.set('n', '<space>wr', vim.lsp.buf.remove_workspace_folder, bufopts)
   vim.keymap.set('n', '<space>wl', function()
      print(vim.inspect(vim.lsp.buf.list_workspace_folders()))
   end, bufopts)
   vim.keymap.set('n', '<space>D', vim.lsp.buf.type_definition, bufopts)
   vim.keymap.set('n', '<space>rn', vim.lsp.buf.rename, bufopts)
   vim.keymap.set('n', '<space>ca', vim.lsp.buf.code_action, bufopts)
   vim.keymap.set('n', 'gr', vim.lsp.buf.references, bufopts)
   vim.keymap.set('n', '<space>f', function() vim.lsp.buf.format { async = true } end, bufopts)
end

---@ nx.map

nx.map({
   { "<space>e", vim.diagnostic.open_float },
   { "[d", vim.diagnostic.goto_prev },
   { "]d", vim.diagnostic.goto_next },
   { "<space>q", vim.diagnostic.setloclist },
}, { noremap = true, silent = true })

local on_attach = function(client, bufnr)
   nx.map({
      { "gD", vim.lsp.buf.declaration },
      { "gd", vim.lsp.buf.definition },
      { "K", vim.lsp.buf.hover },
      { "gi", vim.lsp.buf.implementation },
      { "<C-k>", vim.lsp.buf.signature_help },
      { "<space>wa", vim.lsp.buf.add_workspace_folder },
      { "<space>wr", vim.lsp.buf.remove_workspace_folder },
      { "<space>wl", function() print(vim.inspect(vim.lsp.buf.list_workspace_folders())) end },
      { "<space>D", vim.lsp.buf.type_definition },
      { "<space>rn", vim.lsp.buf.rename },
      { "<space>ca", vim.lsp.buf.code_action },
      { "gr", vim.lsp.buf.references },
      { "<space>f", function() vim.lsp.buf.format { async = true } end },
   }, { noremap = true, silent = true, buffer = bufnr })
end

Custom which-key labels

Register which-key labels that should differ from the mappings' description. They can be a string literal, "ignore"(^="which_key_ignore"), or { sub_desc = "<pattern>" } to exclude a pattern of the mappings desc key.

^{E.g., Search group}
^{🟣 desc labels | 🔵 custom labels} ^{E.g., Toggle group}
^{🟣 desc labels | 🔵 custom labels} ^{Preserve searchable description} ^{e.g.: :Telescope keymaps}

The example below uses wk_label for a "SnipRun-keymap-family". It excludes the string "SnipRun" from being added to every entry on their which-key page.

---@ method 1: a custom `wk_label` per key
nx.map({
   { "<leader>Rc", "<Cmd>SnipClose<CR>", desc = "Close SnipRun", wk_label = "Close" },
   { "<leader>Rf", "<Cmd>%SnipRun<CR>", desc = "Run File" },
   { "<leader>Ri", "<Cmd>SnipInfo<CR>", desc = "SnipRun Info", wk_label = "Info" },
   { "<leader>Rm", "<Cmd>SnipReplMemoryClean<CR>", desc = "SnipRun Clean Memory", wk_label = "Clean Memory" },
   { "<leader>Rr", "<Cmd>SnipReset<CR>", desc = "Reset SnipRun", wk_label = "Reset" },
   { "<leader>Rx", "<Cmd>SnipTerminate<CR>", desc = "Terminate SnipRun", wk_label = "Terminate" },
   { "<leader>R", "<Esc><Cmd>'<,'>SnipRun<CR>", "v", desc = "SnipRun Range", wk_label = "Run Range" },
})

---@ method 2: use `sub_desc` in `wrapper_opts` to remove `SnipRun` from all entries
nx.map({
   { "<leader>Rc", "<Cmd>SnipClose<CR>", desc = "Close SnipRun" },
   { "<leader>Rf", "<Cmd>%SnipRun<CR>", desc = "Run File" },
   { "<leader>Ri", "<Cmd>SnipInfo<CR>", desc = "SnipRun Info" },
   { "<leader>Rm", "<Cmd>SnipReplMemoryClean<CR>", desc = "SnipRun Clean Memory" },
   { "<leader>Rr", "<Cmd>SnipReset<CR>", desc = "Reset SnipRun" },
   { "<leader>Rx", "<Cmd>SnipTerminate<CR>", desc = "Terminate SnipRun" },
   { "<leader>RR", "<Esc><Cmd>'<,'>SnipRun<CR>", "v", desc = "SnipRun Range" },
}, { wk_label = { sub_desc = "SnipRun" } })

Type Annotations

Allow your language server to assist you with hovers, completions, and diagnostics.

^{function hover}	^{field hover}
^cmp	^diagnostic

This requires your runtime environment to be configured to include your plugin directories. An easy way is to have this automated using folke/neodev.nvim.

nx.hl

Based on nvim_set_hl()

nx.hl({
 { "LineNr", fg = "DraculaComment:fg" },
 { "Normal", bg = "DraculaBg:bg" },
 { "BgDarker", bg = palette.bg .. ":#b-15" },
 { "BufferLineSeparatorShadow", fg = "TabLine:bg:#b-10", bg = "Normal:bg" } }
 { { "Directory", "MarkSign" }, link = "DraculaPurple" },
})

Differences

Set single or multiple highlights
The only required values are index [1]: hl_name and bg|fg|link|…: value
ns_id: defaults to 0 and instead of being passed as index [1] it is optional as [3] or ns_id key
values: are passed inline instead of in a separate table
modifiers for values:
- :bg|:fg: to use single values of other highlights as color source instead of linking the whole group.
- :#b: to transform the brightness of a color
{<wrapper_opts>} to add values to all highlights within a nx.hl()

Detailed Examples _{^{Toggle visibility...}}

Feature overview

nx.hl({ "GitSignsCurrentLineBlame", fg = "Debug:fg", bg = "CursorLine:bg", italic = true })
---@ ╰── set a single highlight
---@ ╭── or lists of highlights
nx.hl({
   { "Hex", fg = "#9370DB" },            --   ╮
   { "ColorName", fg = "MediumPurple" }, ---@ ├  kinds of values already possible without nx.nvim
   { "Decimal", fg = 9662683 },          --   ╯
   --
   { "Winbar", fg = "DraculaComment:fg" },
   ---@                       ╭────╯  use single values from other highlight groups
   { "Normal", bg = "DraculaBg:bg" },
   ---@ use a color with transformed brightness  ──╮ ╭─ darken
   { "BufferLineSeparatorShadow", fg = "TabLine:bg:#b-10", bg = "Normal:bg" } }
   ---@ e.g., with hex var ──╮         ╭─ brighten
   { "BgLight", bg = palette.bg .. ":#b+15" },
   ---@           ╭── multiple highlight names
   { { "Directory", "MarkSign" }, link = "DraculaPurple" },
}, { bold = true, italic = true })
---@    ╰── wrapper opts apply values to all entries

Wrapper options

Add values to all entries in a list of highlights - inline values are treated with higher priority and won't be overwritten by wrapper options.

nx.hl({
   { "NeoTreeTabActive", bg = "NeoTreeNormal:bg" },
   { "NeoTreeTabInactive", fg = "NeoTreeDimText:fg" },   -- ╮
   { "NeoTreeTabSeparatorInactive", fg = "TabLine:bg" }, -- ┤
}, { bg = "TabLine:bg" }) ---@    applies `bg` these     -- ╯

nx.au

Based on nvim_create_autocmd()

nx.au({
   { "BufWritePost", pattern = "options.lua", command = "source <afile>", desc = "Execute files on save" },
   { "BufWritePre", command = "call mkdir(expand('<afile>:p:h'), 'p')", desc = "Create non-existent parents" },
})
nx.au({
   { "BufWinLeave", pattern = "*.*", command = "mkview" },
   { "BufWinEnter", pattern = "*.*", command = "silent! loadview" },
}, { create_group = "RememberFolds" })

Differences

Create single or multiple auto commands
opts: are passed inline instead of in a separate table
- additional options:
  - create_group: to create a group and add the autocmd|autocmd[] to that group
- {<wrapper_opts>} to add values to all autocmds within a nx.au()

Detailed Examples _{^{Toggle visibility...}}

Feature Description

nx.au({ "FocusGained", pattern = "*.*", command = "checktime", desc = "Check if buffer changed outside of vim" })
---@ ╰── create a single autocommand
---@ ╭── or lists of autocommands
nx.au({
   { "BufWinLeave", pattern = "*.*", command = "mkview" },
   { "BufWinEnter", pattern = "*.*", command = "silent! loadview" },
}, { pattern = "*.*" })
---@     ╰── wrapper opts apply values to all entries without them

Autocommand groups

Besides the usual adding to existing autocommand groups using the group key, it is possible to create autocommand groups on the fly with the create_group key.

nx.au({
   "BufWritePre",
   -- group = "FormatOnSave", ---@ use `group` as usual to add the autocmd to an already existing group
   create_group = "FormatOnSave", ---@ or create a new group while creating the autocmd
   callback = function()
      if next(vim.lsp.get_active_clients({ bufnr = 0 })) == nil then return end
      vim.lsp.buf.format({ async = false })
   end,
})
nx.au({
   { "BufWinLeave", pattern = "*.*", command = "mkview" },
   { "BufWinEnter", pattern = "*.*", command = "silent! loadview" },
   ---@   ╭── create an autocommand group in `wrapper_opts` and add all autocommands within this "nx.au()" call
}, { create_group = "RememberFolds" })

nx.cmd

Based on nvim_create_user_command()

nx.cmd({
  "LspFormat",
  function() vim.lsp.buf.format({ async = true }) end,
  bang = true,
  desc = "Fromat the Current Buffer",
})

Differences

Create single or multiple commands
The only required values are index [1]: name and [2]: command
opts: are passed inline instead of in a separate table
{<wrapper_opts>} to add values to all commands within a nx.cmd()

Detailed Examples _{^{Toggle visibility...}}

Feature Description

---@ ╭── create a single command
nx.cmd({ "ResetTerminal", function() vim.cmd("set scrollback=1 | sleep 10m | set scrollback=10000") end })
---@ ╭── or lists of commands
nx.cmd({
   { "LspFormat", function() vim.lsp.buf.format({ async = true }) end },
   { "LspToggleAutoFormat", function(opt) toggle_format_on_save(opt.args) end, nargs = "?" },
   { "ToggleBufferDiagnostics", function() toggle_buffer_diags(vim.fn.bufnr()) end },
}, { bang = true })
---@   ╰── wrapper opts apply options to all entries without them

nx.set

There is also nx.set to assign multiple variables or options.

Next to an array of variables/settings, add the scope (vim.g|vim.opt|vim.bo|...) as a second parameter. If no scope is specified vim.g is used.

(This features function currently consists of just over 10 lines of code. It's not as extensive or well annotated, but feel free to use it if you like).

Details _{^{Toggle visibility...}}

Variables

nx_set({
   dracula_italic = 1,
   dracula_bold = 1,
   dracula_full_special_attrs_support = 1,
   dracula_colorterm = 0,
})
-- common way:
vim.g.dracula_italic = 1
vim.g.dracula_bold = 1
vim.g.dracula_full_special_attrs_support = 1
vim.g.dracula_colorterm = 0

Options

nx.set({
   -- General
   clipboard = "unnamedplus", -- use system clipboard
   mouse = "a", -- allow mouse in all modes
   showmode = false, -- print vim mode on enter
   termguicolors = true, -- set term gui colors
   timeoutlen = 350, -- time to wait for a mapped sequence to complete
   fillchars__append = [[eob: ,fold: ,foldopen:,foldsep: ,foldclose:›, vert:▏]],
   listchars__append = [[space:⋅, trail:⋅, eol:↴]],
   -- Auxiliary files
   undofile = true, -- enable persistent undo
   backup = false, -- create a backup file
   swapfile = false, -- create a swap file
   -- Command line
   cmdheight = 0,
   -- Completion menu
   pumheight = 14, -- completion popup menu height
   shortmess__append = "c", -- don't give completion-menu messages
   -- Gutter
   number = true, -- show line numbers
   numberwidth = 3, -- number column width - default "4"
   relativenumber = true, -- set relative line numbers
   signcolumn = "yes:2", -- use fixed width signcolumn - prevents text shift when adding signs
   -- Search
   hlsearch = true, -- highlight matches in previous search pattern
   ignorecase = true, -- ignore case in search patterns
   smartcase = true, -- use smart case
   -- ...
}, vim.opt)

Getting Started

Install "tenxsoydev/nx.nvim" via your favorite plugin manager.

The only thing left to do then is to import the nx functions you want to use.

Examples

Set it once as global variable, so it can be called anywhere in a configuration

-- if using a global variable, make sure it's set where it will be loaded before it's used in another place
_G.nx = require("nx")
-- use anywhere
nx.map({})
nx.au({})
nx.hl({})

-- E.g., when using a plugin manger like lazy, add a high priority
require("lazy").setup({
  -- ...
  { "tenxsoydev/nx.nvim", priority = 100, config = function() _G.nx = require "nx" end },
  -- ...
})

-- or if you prefer not to have the `nx` branding, use another vairable name
_G.v = require("nx")
-- use anywhere
v.map({})
v.au({})
v.hl({})

It's also possible to import single modules on demand

local map = require("nx.map")
local hl = require("nx.hl")
local au = require("nx.au")

Reusability

To be easily composable, the utilities are written as single modules that can stand on their own. So if they can be helpful within the project you are working - and adding dependencies is too heavy - they are light copy pasta 🍝. In such cases, keeping a small reference of attribution warms the heart of your fellow developer.

Contribution

There is always room for enhancement. Reach out if you experience any issues, would like to request a feature, or submit improvements. If you would like to tackle open issues - they are usually "help wanted" by nature. Leaving an emoji to show support for an idea that has already been requested also helps to prioritize community needs.

Credits

nxvim

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

nx.nvim

Features

nx.map

Feature overview

Mode

Wrapper options

Custom which-key labels

Type Annotations

nx.hl

Feature overview

Wrapper options

nx.au

Feature Description

Autocommand groups

nx.cmd

Feature Description

nx.set

Getting Started

Examples

Reusability

Contribution

Credits

Files

README.md

Latest commit

History

README.md

File metadata and controls

nx.nvim

Features

nx.map

Feature overview

Mode

Wrapper options

Custom which-key labels

Type Annotations

nx.hl

Feature overview

Wrapper options

nx.au

Feature Description

Autocommand groups

nx.cmd

Feature Description

nx.set

Getting Started

Examples

Reusability

Contribution

Credits