neovim/node-client is a Developer Tools project on GitHub, written primarily in TypeScript. It has 536 stars. Nvim Node.js client and plugin host
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
For "remote plugins", the Nvim Node.js provider expects the neovim package to be globally installed:
npm install -g neovim
Or for non-plugin purposes, neovim works like any other NPM package.
See below for a quickstart example that you can copy and run immediately.
Requirements
Node.js 16 and later is tested. Older versions of Node.js may work but are not tested.
Usage
Functions
The neovim package provides these functions:
attach(): The primary interface. Takes a process, socket, or pair of write/read streams and returns a NeovimClient connected to an nvim process.
findNvim(): Tries to find a usable nvim binary on the current system.
Logging
At load-time, the neovim module replaces ("monkey patches") console with its logger
interface, so console.log will call logger.info instead of writing to stdout (which would
break the stdio RPC channel).
To skip this patching of console.log, pass a custom logger to attach().
Best practice in any case is to use the logger available from the NeovimClient returned by
attach(), instead of console logging functions.
Set the $NVIM_NODE_LOG_FILE env var to (also) write logs to a file.
Set the $ALLOW_CONSOLE env var to (also) write logs to stdout. This will break any (stdio) RPC
channel because logs written to stdout are invalid RPC messages.
Quickstart: connect to Nvim
Following is a complete, working example.
Install the neovim package locally in any directory (i.e. without -g. Node throws ERR_MODULE_NOT_FOUND if a script imports a globally installed package).
npm install neovim
# Or if build from source:
npm run build
Paste the script below into a demo.mjs file and run it!
ALLOW_CONSOLE=1 node demo.mjs
$ALLOW_CONSOLE env var must be set, because logs are normally not printed to stdout.
Note: $ALLOW_CONSOLE is only for demo purposes. It cannot be used for remote plugins or
whenever stdio is an RPC channel, because writing logs to stdout would break the RPC
channel.
Script:
import * as child_process from 'node:child_process';
import * as assert from 'node:assert';
import { attach, findNvim } from 'neovim';
// Find `nvim` on the system and open a channel to it.
(async function () {
const found = findNvim({ orderBy: 'desc', minVersion: '0.9.0' });
console.log(found);
const [arg0, ...args] = found.matches[0].cmd;
const nvim_proc = child_process.spawn(arg0, [...args, '--clean', '--embed'], {});
const nvim = attach({ proc: nvim_proc });
nvim.command('vsp | vsp | vsp');
const windows = await nvim.windows;
assert.deepStrictEqual(windows.length, 4);
assert.ok(windows[0] instanceof nvim.Window);
nvim.window = windows[2];
const win = await nvim.window;
assert.ok(win.id !== windows[0].id);
assert.deepStrictEqual(win.id, windows[2].id);
const buf = await nvim.buffer;
assert.ok(buf instanceof nvim.Buffer);
const lines = await buf.lines;
assert.deepStrictEqual(lines, []);
await buf.replace(['line1', 'line2'], 0);
const newLines = await buf.lines;
assert.deepStrictEqual(newLines, ['line1', 'line2']);
if (nvim_proc.disconnect) {
nvim_proc.disconnect();
}
nvim.quit();
while (nvim_proc.exitCode === null) {
await new Promise(resolve => setTimeout(resolve, 100));
console.log('waiting for Nvim (pid %d) to exit', nvim_proc.pid);
}
console.log('Nvim exit code: %d', nvim_proc.exitCode);
})();
Create a remote plugin
Neovim supports remote plugins, which are plugins implemented as Nvim API clients.
This package contains both the "API client" (which talks to nvim) and "remote plugin host" (which discovers and runs Nvim node.js remote plugins).
You can define a remote plugin as a file or folder in an rplugin/node/ directory on Nvim's 'runtimepath'.
If the plugin is a folder, the main script from package.json will be loaded.
The plugin must export a function which takes a NvimPlugin object as its only parameter. You may then register autocmds, commands and functions by calling methods on the NvimPlugin object.
Avoid heavy initialisation or async functions at this stage, because Nvim may only be collecting information about your plugin without wishing to actually use it.
Instead, wait for one of your autocmds, commands or functions to be called before starting any processing.
Remote plugin examples
See examples/ for remote plugin examples.
Remote plugin API
NvimPlugin.nvim;
This is the nvim api object you can use to send commands from your plugin to nvim.
Set your plugin to dev mode, which will cause the module to be reloaded on each invocation.
alwaysInit will always attempt to attempt to re-instantiate the plugin. e.g. your plugin class will
always get called on each invocation of your plugin's command.
Registers an autocmd for the event name, calling your function fn with options. Pattern is the only required option. If you wish to call a method on an object you may pass fn as an array of [object, object.method].
By default autocmds, commands and functions are all treated as asynchronous and should return Promises (or should be async functions).
Registers a function with name name, calling function fn with options. This will be invoked from nvim by entering eg :call name() in normal mode.
Debug / troubleshoot
For debugging and configuring logging, you can set the following environment variables which are used by the neovim package (or nvim itself where noted):
NVIM_NODE_HOST_DEBUG: Spawns the node process that calls neovim-client-host with --inspect-brk so you can have a debugger.
Pair that with this Node Inspector Manager Chrome plugin
Logging: Logging is done using winston through the logger module. This package replaces console with this interface.
NVIM_NODE_LOG_LEVEL: Sets the logging level for winston. Default is debug.
Available levels: { error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5 }
NVIM_NODE_LOG_FILE: Sets the log file path.
Usage through node REPL
NVIM_LISTEN_ADDRESS:
Start Nvim with a known address (or use the $NVIM_LISTEN_ADDRESS of a running instance):
$ NVIM_LISTEN_ADDRESS=/tmp/nvim nvim
In another terminal, connect a node REPL to Nvim
// `scripts/nvim` will detect if `NVIM_LISTEN_ADDRESS` is set and use that unix socket
// Otherwise will create an embedded `nvim` instance
require('neovim/scripts/nvim').then(nvim => {
nvim.command('vsp');
});
See the tests and scripts for more examples.
Develop
After cloning the repo, run npm install to install dev dependencies. The main neovim library is in packages/neovim.
Run tests
npm run build && NVIM_NODE_LOG_FILE=log npm run test
Maintain
Release
Only maintainers of the neovim NPM package can publish a release. Follow these steps to publish a release:
Update CHANGELOG.md.
Update version. Build and publish the package. Tag the release and push.
# Choose major/minor/patch as needed.
npm version --no-git-tag-version patch
npm version -w packages/neovim/ patch
git add package*.json packages/neovim/package.json
git commit -m 'release'
# Note: this copies the top-level README.md/CHANGELOG.md to packages/neovim/.
npm run publish:neovim
export _VERSION=$(grep -o 'version": "[^"]\+' packages/neovim/package.json | sed 's/.*"//') && echo $_VERSION
git tag "v${_VERSION}"
git push --tags
git push
Post-release tasks:
Add stub to CHANGELOG.md.
Bump and commit.
npm version --no-git-tag-version prerelease --preid dev
npm version -w packages/neovim/ --no-git-tag-version prerelease --preid dev
git add package*.json packages/neovim/package.json
git commit -m bump
git push
Regenerate documentation website
The docs website is currently not automated. Follow these steps to regenerate it:
The most recent commit recorded on neovim/node-client was 27 days ago, based on the GitHub push timestamp. The repository has 59 forks — one of the better signals of community interest.
How many stars does neovim/node-client have?
neovim/node-client has 536 GitHub stars — refresh the page for the live number, or check github.com/neovim/node-client. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is neovim/node-client open source?
Yes — neovim/node-client ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/neovim/node-client.
What else is in the Developer Tools space?
neovim/node-client is tracked by TopGit under the Developer Tools category, alongside 6 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is neovim/node-client?
neovim/node-client (neovim/node-client) is a TypeScript project on GitHub. From the project's own README: Nvim Node.js client and plugin host
What language is neovim/node-client written in?
neovim/node-client is written primarily in TypeScript. GitHub's language field is based on the largest share of bytes in the default branch.
What license does neovim/node-client use?
neovim/node-client is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about neovim/node-client?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/neovim/node-client is the definitive source.
Read full README in the tab above.
Curious whether node-client is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about node-client.