VSCode Neovim

VSCode Neovim Integration

Neovim is a fork of Vim to allow greater extensibility and integration. This extension uses a fully embedded Neovim instance, no more half-complete Vim emulation! VSCode's native functionality is used for insert mode and VSCode commands, making the best use of both editors.

• 🎉 Feature-complete Vim integration (except insert-mode and some Nvim UI plugins) by utilizing Nvim as a backend.
• 🔧 Supports custom init.lua and most Nvim plugins.
• 🥇 First-class and lag-free insert mode, letting VSCode do what it does best.
• 🤝 Complete integration with VSCode features (lsp/autocompletion/snippets/multi-cursor/etc).

• 🧰 Getting Started

• 💡 Tips and Features

• ⚡️ API

• ⌨️ Keybindings (shortcuts)

• 📟 Neovim Commands

• 🎨 Highlights
• 🧰 Developing
• ❤️ Credits \& External Resources

🧰 Getting Started

Installation

• Install the vscode-neovim extension.
• Install Neovim 0.10.0 or newer.

• If you want to use Neovim from WSL, set the useWSL configuration toggle and specify the Linux path to the nvim

• Assign affinity value for performance improvement.

Snap Users: If you want to use Neovim from Snap, the Neovim path must be resolved to the snap binary location. On

some systems it might be "/snap/nvim/current/usr/bin/nvim". To check if you're running as a snap package, see if

which nvim resolves to /usr/bin/snap.

Neovim configuration

Since many Vim plugins can cause issues in VSCode, it is recommended to start from an empty init.vim. For a guide for which types of plugins are supported, see troubleshooting.

Before creating an issue on Github, make sure you can reproduce the problem with an empty init.vim and no VSCode extensions.

To detect if Nvim is running in VSCode, add to your init.vim:

if exists('g:vscode')
    " VSCode extension
else
    " ordinary Nvim
endif

In lua:

if vim.g.vscode then
    -- VSCode extension
else
    -- ordinary Nvim
end

To conditionally activate plugins, the best solution is to use the LazyVim VSCode extra. However, packer.nvim and lazy.nvim have built-in support for cond = vim.g.vscode and vim-plug has a few solutions. See plugins in the wiki for tips on configuring Vim plugins.

VSCode Settings & Commands

You can view all available settings and commands by opening the vscode-neovim extension details pane, and navigating to the features tab.

💡 Tips and Features

VSCode specific differences

• File and editor management commands such as :e/:q/:vsplit/:tabnext/etc are mapped to corresponding VSCode

• When you type some commands they may be substituted for another, check

• Scrolling is done by VSCode. C-d/C-u/etc are slightly different.
• Editor customization (relative line number, scrolloff, etc) is handled by VSCode.
• Dot-repeat (.) is slightly different - moving the cursor within a change range won't break the repeat.

Troubleshooting

• To fix intermittent problems, you can run the Neovim: Restart Extension command to restart the extension.
• View the logs via Output: Focus on Output View and select vscode-neovim logs.

• Enable vscode-neovim.neovimClean in VSCode settings, which starts Nvim _without_ your plugins (nvim --clean). Nvim

• If you encounter rendering issues (visual artifacts), try CTRL-L to force Nvim to redraw.
• If you get the Unable to init vscode-neovim: command 'type' already exists message, uninstall other VSCode

• On a Mac, the h, j, k and l movement keys may not repeat when held, to fix

• To fix the remapped escape key not working in Linux, set "keyboard.dispatch": "keyCode".
• Two VSCode developer commands are useful for keybindings debugging:

Performance

If you have any performance problems (cursor jitter usually) make sure you're not using vim plugins that increase latency and cause performance problems.

Make sure to disable unneeded plugins, as many of them don't make sense with VSCode. Specifically, you don't need any code highlighting, completion, LSP plugins, or plugins that spawn windows/buffers (nerdtree , fuzzy-finders, etc). Most navigation/textobject/editing plugins should be fine.

For example, make sure you're not using anything that renders decorators very often:

• Line number extensions (VSCode has built-in support for normal/relative line numbers)
• Indent guide extensions (VSCode has built-in indent guides)
• Brackets highlighter extensions (VSCode has built-in feature)

If you're not sure, disable all other extensions, reload VSCode window, and see if the problem persists before

reporting it.

Composite escape keys

Set with compositeKeys and tweak with compositeTimeout.

Examples: add to your settings.json:

jj to escape

{
    "vscode-neovim.compositeKeys": {
        "jj": {
            "command": "vscode-neovim.escape",
        },
    },
}

jk to escape and save

{
    "vscode-neovim.compositeKeys": {
        "jk": {
            // Use lua to execute any logic
            "command": "vscode-neovim.lua",
            "args": [
                [
                    "local code = require('vscode')",
                    "code.action('vscode-neovim.escape')",
                    "code.action('workbench.action.files.save')",
                ],
            ],
        },
    },
}

Jumplist

VSCode's jumplist is used instead of Neovim's. This is to make VSCode native navigation (mouse click, jump to definition, etc) navigable through the jumplist.

Make sure to bind to workbench.action.navigateBack / workbench.action.navigateForward if you're using custom mappings. Marks (both upper & lowercased) should work fine.

Multiple cursors

Multiple cursors work in:

1. Insert mode
2. Visual line mode
3. Visual block mode

• For visual line mode, mi will start insert mode on each selected line on the first non whitespace character

• For visual block mode, mi will start insert on each selected line before the cursor block and ma

• mA/mI versions accounts for empty lines (only for visual line mode, for visual block mode

See gif in action:

!multicursor

Note: The built-in multi-cursor support may not meet your needs. Please refer to the plugin

vscode-multi-cursor.nvim for more multi-cursor features

Remote development

We intend to use vscode-neovim as a UI extension, so when you're using remote development, vscode-neovim is enabled in the Local Extension Host, and it should work out of the box.

If you prefer to use the remote environment's copy of Neovim, rather than the locally installed one, vscode-neovim should be installed in the Remote Extension Host. You can set the following in your VSCode settings.json:

{
    "remote.extensionKind": {
        "asvetliakov.vscode-neovim": ["workspace"]
    }
}

Note: You will need to install neovim in the remote environment.

For more information:

• Remote Development
• Extension Host
• Remote Extensions

⚡️ API

Load the module:

local vscode = require('vscode')

[!TIP]

The previously used module named "vscode-neovim" is now deprecated, so don't be confused if "vscode-neovim" is used in old discussions or other resources.

1. vscode.action(): asynchronously executes a vscode command.
2. vscode.call(): synchronously executes a vscode command.
3. vscode.on(): defines a handler for some Nvim UI events.
4. vscode.has_config(): checks if a vscode setting exists.
5. vscode.get_config(): gets a vscode setting value.
6. vscode.update_config(): sets a vscode setting.
7. vscode.notify(): shows a vscode message (see also Nvim's vim.notify).
8. vscode.to_op(): A helper for map-operator. See code_actions.lua for the

1. g:vscode_clipboard: Clipboard provider using VSCode's clipboard API. Used by default when in WSL. See

1. vscode.eval(): evaluate javascript synchronously in vscode and return the result
2. vscode.eval_async(): evaluate javascript asynchronously in vscode
3. vscode.with_insert(): perform operations in insert mode.

vscode.action(name, opts)

Asynchronously executes a vscode command.

Parameters:

• name (string): The name of the action, generally a vscode command.
• opts (table): Map of optional parameters:

Example: open definition aside (default binding):

nnoremap <C-w>gd <Cmd>lua require('vscode').action('editor.action.revealDefinitionAside')<CR>

Example: find in files for word under cursor (see the vscode command definition for the expected parameter format):

nnoremap ? <Cmd>lua require('vscode').action('workbench.action.findInFiles', { args = { query = vim.fn.expand('<cword>') } })<CR>

Example: use in lua script:

-- Format current document
vscode.action("editor.action.formatDocument")
do -- Comment the three lines below the cursor
  local curr_line = vim.fn.line(".") - 1  -- 0-indexed
  vscode.action("editor.action.commentLine", {
    range = { curr_line + 1, curr_line + 3 },
  })
end
do -- Comment the previous line
  local curr_line = vim.fn.line(".") - 1 -- 0-indexed
  local prev_line = curr_line - 1
  if prev_line >= 0 then
    vscode.action("editor.action.commentLine", {
      range = { prev_line , prev_line },
    })
  end
end
do -- Find in files for word under cursor
  vscode.action("workbench.action.findInFiles", {
    args = { query = vim.fn.expand('<cword>') }
  })
end

Currently, two built-in actions are provided for testing purposes:

1. _ping returns "pong"
2. _wait waits for the specified milliseconds and then returns "ok"

do -- Execute _ping asynchronously and print the result
  vscode.action("_ping", {
    callback = function(err, res)
      if err == nil then
        print(res) -- outputs: pong
      end
    end,
  })
end

vscode.call(name, opts, timeout)

Synchronously executes a vscode command.

Parameters:

• name (string): The name of the action, generally a vscode command.
• opts (table): Same as vscode.action().
• timeout (number): Timeout in milliseconds. The default value is -1, which means there is no timeout.

Example: format selection (default binding):

xnoremap = <Cmd>lua require('vscode').call('editor.action.formatSelection')<CR>
nnoremap = <Cmd>lua require('vscode').call('editor.action.formatSelection')<CR><Esc>
nnoremap == <Cmd>lua require('vscode').call('editor.action.formatSelection')<CR>

Example: use in lua script:

-- Execute _ping synchronously and print the result
print(vscode.call("_ping")) -- outputs: pong
-- Wait for 1 second and print the return value 'ok'
print(vscode.call("_wait", { args = { 1000 } })) -- outputs: ok
-- Wait for 2 seconds with a timeout of 1 second
print(vscode.call("_wait", { args = { 2000 } }), 1000)
-- error: Call '_wait' timed out

vscode.on(event, callback)

Currently no available events for user use.

vscode.has_config(name)

Check if configuration has a certain value.

Parameters:

• name (string|string[]): The configuration name or an array of configuration names.

• boolean|boolean[]: Returns true if the configuration has a certain value, false otherwise. If name is an

Examples:

-- Check if the configuration "not.exist" exists
print(vscode.has_config("not.exist"))
-- Should return: false
-- Check multiple configurations
vim.print(vscode.has_config({ "not.exist", "existing.config" }))
-- Should return: { false, true }

vscode.get_config(name)

Get configuration value.

Parameters:

• name (string|string[]): The configuration name or an array of configuration names.

• unknown|unknown[]: The value of the configuration. If name is an array, returns an array of values corresponding

Examples:

-- Get the value of "editor.tabSize"
print(vscode.get_config("editor.tabSize")) -- a number
-- Get multiple configurations
vim.print(vscode.get_config({ "editor.fontFamily", "editor.tabSize" }))
-- Should return: { "the font family", "the editor tabSizse" }

vscode.update_config(name, value, target)

Update configuration value.

Parameters:

• name (string|string[]): The configuration name or an array of configuration names.
• value (unknown|unknown[]): The new value for the configuration.
• target ("global"|"workspace"|"workspace_folder"): The configuration target. Optional, defaults to

Examples:

-- Update the value of "editor.tabSize"
vscode.update_config("editor.tabSize", 16, "global")
-- Update multiple configurations
vscode.update_config({ "editor.fontFamily", "editor.tabSize" }, { "Fira Code", 14 })

vscode.notify(msg)

Show a vscode notification

You can set vscode.notify as your default notify function.

vim.notify = vscode.notify

vscode.eval(code[, opts, timeout])

Evaluate javascript inside vscode and return the result. The code is executed in an async function context (so await can be used). Use a return statement to return a value back to lua. Arguments passed from lua are available as the args variable. The evaluated code has access to the VSCode API through the vscode global.

Tips:

• Make sure to await on asynchronous functions when accessing the API.
• Use the global logger (e.g. logger.info(...)) to log messages to the output of vscode-neovim.
• JSON serializable values (primitives and simple objects) can be returned and will be automatically serialized then

• globalThis['some_name'] = ... can be used to persist values between calls.

• code (string): The javascript to execute.
• opts (table): Map of optional parameters:

• timeout (number): The number of milliseconds to wait for the evaluation to complete before cancelling. By default

Returns:

• The result of executing the provided code.

local current_file = vscode.eval("return vscode.window.activeTextEditor.document.fileName")
local current_tab_is_pinned = vscode.eval("return vscode.window.tabGroups.activeTabGroup.activeTab.isPinned")
vscode.eval("await vscode.env.clipboard.writeText(args.text)", { args = { text = "some text" } })

vscode.eval_async(code[, opts])

Like vscode.eval() but returns immediately and evaluates in the background instead.

Parameters:

• code (string): The javascript to execute.
• opts (table): Map of optional parameters:

vscode.with_insert(callback[, ms])

Perform operations in insert mode. If in visual mode, this function will preserve the selection after switching to insert mode.

Parameters:

• callback (function): Callback function to run after switching to insert mode
• ms (number, optional): Milliseconds to defer the callback. Defaults to 30.

vim.keymap.set({ "n", "x", "i" }, "<C-d>", function()
  vscode.with_insert(function()
    vscode.action("editor.action.addSelectionToNextFindMatch")
  end)
end)

!select-next

Example: make "editor.action.refactor" work correctly on the selection and support snippet manipulation after entering VSCode snippet mode.

vim.keymap.set({ "n", "x" }, "<leader>r", function()
  vscode.with_insert(function()
    vscode.action("editor.action.refactor")
  end)
end)

!refactor

Builtin module overrides

1. vim.ui: use VSCode's UI components.
2. vim.lsp.buf: execute corresponding VSCode LSP commands.

VimScript

Note: Since 1.0.0, vimscript functions are deprecated. Use the Lua api instead.

• VSCodeNotify()/VSCodeCall(): deprecated, use Lua require('vscode').call() instead.
• VSCodeNotifyRange()/VSCodeCallRange(): deprecated, use Lua

• VSCodeNotifyRangePos()/VSCodeCallRangePos(): deprecated, use Lua

You can also use v:lua.require("vscode") to access the API from VimScript.

⌨️ Keybindings (shortcuts)

There are three types of default/user keybindings:

• Neovim keybindings: These are the keybindings that are defined in the extension's vimscript files or the user's

• VSCode keybindings: These are the keybindings that are defined in the extension's package.json or the user's

• VSCode passthrough keybindings: These are the keybindings that are defined in the extension's package.json or

This document only mentions some special cases, it is not an exhaustive list of keybindings and commands. Use VSCode and Nvim features to see documentation and all defined shortcuts:

• Run the Preferences: Open Keyboard Shortcuts vscode command and search for "neovim" to see all vscode and

• Use the Nvim :help command to see the documentation for a given neovim command or keybinding. For example try

• Search the online Nvim documentation:
• Reference the VSCode docs:

Keybinding Passthroughs

Every special (control/alt/non-alphanumerical) keyboard shortcut must be explicitly defined in VSCode to send to neovim. By default, only bindings that are used by Neovim by default are sent.

Note: if you want to pass additional control keys without adding a custom passthrough, see below.

To add a custom passthrough, for example A-h in normal mode, add to your keybindings.json:

{
    "command": "vscode-neovim.send",
    // Invoke the binding with this key sequence.
    "key": "alt+h",
    // Don't activate during insert mode.
    // Docs for "when": https://code.visualstudio.com/api/references/when-clause-contexts
    "when": "editorTextFocus && neovim.mode != insert",
    // Send this input to Neovim.
    "args": "<A-h>",
}

Insert mode control keys passthrough

Set by vscode-neovim.ctrlKeysForInsertMode.

Default: ["a", "d", "h", "j", "m", "o", "r", "t", "u", "w"]

Normal mode control keys passthrough

Set by ctrlKeysForNormalMode.

Default: ["a", "b", "d", "e", "f", "h", "i", "j", "k", "l", "m", "o", "r", "t", "u", "v", "w", "x", "y", "z", "/", "]"]

Cmdline mode special keys passthrough

Always enabled.

• Tab, Up, Down
• Ctrl keys:
• All prefixed keys

Disable passthrough for certain filetypes

Set by editorLangIdExclusions.

Disable keybindings defined by this extension in certain filetypes. Please note that this will not affect all keybindings.

Remove other vscode or passthrough keybindings

If the above configuration flags do not provide enough control, you can remove the keybindings by editing your keybindings.json or using the VSCode keybindings editor:

!remove keybindings

Code navigation bindings

| Key | VSCode Command | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | = / == | editor.action.formatSelection | | gh / K | editor.action.showHover | | gd / C-] | editor.action.revealDefinition
Also works in vim help. | | gf | editor.action.revealDeclaration | | gH | editor.action.referenceSearch.trigger | | gO | workbench.action.gotoSymbol | | C-w gd / C-w gf | editor.action.revealDefinitionAside | | gD | editor.action.peekDefinition | | gF | editor.action.peekDeclaration | | Tab | togglePeekWidgetFocus
Switch between peek editor and reference list. | | C-n / C-p | Navigate lists, parameter hints, suggestions, quick-open, cmdline history, peek reference list |

💡 To specify the default peek mode, modify editor.peekWidgetDefaultFocus in your settings.

Explorer/list navigation bindings

| Key | VSCode Command | | ----------------------------------- | ------------------------------- | | j or k | list.focusDown/Up | | h or l | list.collapse/select | | Enter | list.select | | gg | list.focusFirst | | G | list.focusLast | | o | list.toggleExpand | | C-u or C-d | list.focusPageUp/Down | | zo or zO | list.expand | | zc | list.collapse | | zC | list.collapseAllToFocus | | za or zA | list.toggleExpand | | zm or zM | list.collapseAll | | / or Escape | list.toggleKeyboardNavigation |

Explorer file manipulation bindings

| Key | VSCode Command | | ------------ | --------------------------------------------- | | r | renameFile | | d | deleteFile | | y | filesExplorer.copy | | x | filesExplorer.cut | | p | filesExplorer.paste | | v | explorer.openToSide | | a | explorer.newFile | | A | explorer.newFolder | | R | workbench.files.action.refreshFilesExplorer |

Hover widget manipulation bindings

| Key | VSCode Command | | -------------- | -------------------------------- | | K | editor.action.showHover | | h | editor.action.scrollLeftHover | | j | editor.action.scrollDownHover | | k | editor.action.scrollUpHover | | l | editor.action.scrollRightHover | | gg | editor.action.goToTopHover | | G | editor.action.goToBottomHover | | C-f | editor.action.pageDownHover | | C-b | editor.action.pageUpHover |

📟 Neovim Commands

Default commands and bindings are available for file/scroll/window/tab management.

File management

See vscode-file-commands.vim for file commands reference.

The extension aliases various Nvim commands (:edit, :enew, :find, :quit, etc.) to equivalent vscode commands. Also their normal-mode equivalents (where applicable) such as C-w q, etc.

Tab management

See vscode-tab-commands.vim for tab commands reference.

The extension aliases various Nvim tab commands (:tabedit, :tabnew, :tabfind, :tabclose, :tabnext, :tabprevious, :tabfirst, :tablast) to equivalent vscode commands. Also their normal-mode equivalents (where applicable) such as gt, etc.

Buffer/window management

See vscode-window-commands.vim for file commands reference.

The extension aliases various Nvim buffer/window commands (:split, :vsplit, :new, :vnew, :only) to equivalent vscode commands. Also their normal-mode equivalents (where applicable) such as C-w s, etc.

💡 Split size distribution is controlled by workbench.editor.splitSizing setting. By default, it's distribute,

which is equal to vim's equalalways and eadirection = 'both' (default).

To use VSCode command 'Increase/decrease current view size' instead of separate bindings for width and height:

• workbench.action.increaseViewSize
• workbench.action.decreaseViewSize

function! s:manageEditorSize(...)
    let count = a:1
    let to = a:2
    for i in range(1, count ? count : 1)
        call VSCodeNotify(to ==# 'increase' ? 'workbench.action.increaseViewSize' : 'workbench.action.decreaseViewSize')
    endfor
endfunction
" Sample keybindings. Note these override default keybindings mentioned above.
nnoremap <C-w>> <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
xnoremap <C-w>> <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
nnoremap <C-w>+ <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
xnoremap <C-w>+ <Cmd>call <SID>manageEditorSize(v:count, 'increase')<CR>
nnoremap <C-w>< <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>
xnoremap <C-w>< <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>
nnoremap <C-w>- <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>
xnoremap <C-w>- <Cmd>call <SID>manageEditorSize(v:count, 'decrease')<CR>

🎨 Highlights

There are two ways to customize highlight colors:

1. Set colors in nvim

1. Set colors in vscode

🧰 Developing

Please see CONTRIBUTING.md for details on how to contribute to this project.

❤️ Credits & External Resources

• vim-altercmd - Used for rebinding default commands to call VSCode command.
• neovim nodejs client - NodeJS library for communicating with Neovim.
• VSCodeVim - Used for various inspiration.