Bunvim is a Bun client that allows you to interact with Neovim through RPC using TypeScript and JavaScript. If you're familiar with Neovim's Lua API, you'll find this client easy to use.
This client includes TypeScript definitions, generated from Neovim's api-metadata, describing API function signatures, including function parameters and return values.
All functionality is implemented in one file. If you're looking for higher levels of abstraction, take a look at neovim/node-client and neoclide/neovim. Good luck.
bun install bunvimFor examples of plugins using Bunvim, take a look at ghost-text.nvim and github-preview.nvim.
You should keep a tab open with Neovim API docs when working with Bunvim. Although this client includes generated TypeScript types, you'll find the detailed descriptions in the official docs very helpful if not necessary.
Create a script:
// my-plugin.ts
import { attach } from "bunvim";
// RPC listenning address
const SOCKET = "/tmp/bunvim.nvim.socket";
const nvim = await attach({
socket: SOCKET,
client: { name: "my-plugin-name" },
});
// append "hello world" to current buffer
await nvim.call("nvim_buf_set_lines", [0, -1, -1, true, ["hello world"]]);
// disable relative numbers
await nvim.call("nvim_set_option_value", ["relativenumber", false, {}]);
// create a vertical split
await nvim.call("nvim_command", ["vs"]);
// print cursor position on cursor move
await nvim.call("nvim_create_autocmd", [
["CursorHold", "CursorHoldI"],
{
desc: "Print Cursor Position",
command: `lua
local cursor_pos = vim.api.nvim_win_get_cursor(0)
vim.print(cursor_pos)`,
},
]);
nvim.detach();Initialize Neovim with the RPC listening address specified above:
nvim --listen /tmp/bunvim.nvim.socketExecute your script from another terminal:
bun run my-plugin.tsIf your plugin is executed as a child process of Neovim:
-- somewhere in your neovim lua config files
local function run_script()
-- neovim sets the environment variable NVIM in all its child processes
-- NVIM = the RPC listening address assigned to the current neovim instance
-- neovim sets an RPC listening address if you don't manually specify one
-- https://neovim.io/doc/user/builtin.html#jobstart-env
vim.fn.jobstart("bun run my-plugin.ts", {
cwd = vim.fn.expand("~/path/to/plugin/"),
})
end
vim.api.nvim_create_user_command("RunMyScript", run_script, {})You could then open Neovim without manually specifying an RPC listening address, just nvim and then run the command :RunMyScript.
Your Bun process would then have access to the NVIM environment variable.
// my-plugin.ts
import { attach } from "bunvim";
const SOCKET = process.env["NVIM"];
if (!SOCKET) throw Error("socket missing");
const nvim = await attach({
socket: SOCKET,
client: { name: "my-plugin-name" },
});This module exports only one method attach and a bunch of TypeScript types. attach returns
an Nvim object that can be used to interact with Neovim.
nvim.call(function: string, args: unknown[])
Used to call any of these functions. They're all typed. You should get function names autocompletion & warnings from TypeScript if the parameters don't match the expected types. Some function calls return a value, others don't.
const bufferContent = await nvim.call("nvim_buf_get_lines", [0, 0, -1, true]);
nvim.channelId
RPC Channel ID.
const channelId = nvim.channelId; await nvim.call("nvim_create_autocmd", [ ["CursorMove"], { desc: "Notify my-plugin", command: `lua vim.rpcnotify(${channelId}, "my-notification")`, }, ]);
nvim.onNotification(notification: string, callback: function)
Registers a handler for a specific RPC Notification.
Notifications must be typed before you declare a handler for them, or TypeScript will complain.
import { attach, type BaseEvents, type EventsMap } from "bunvim"; // an interface to define your notifications and their args interface MyEvents extends BaseEvents { requests: EventsMap; // default type notifications: { // declare custom notification: "cursor_move", // that would be called with args: [row: number, col: number] "cursor_move": [row: number, col: number]; }; } // attach to neovim const nvim = await attach<MyEvents>({ ... }) let count = 0; // register a handler for the notification "cursor_move" nvim.onNotification("cursor_move", async ([row, col]) => { // "row" and "col" are of type "number" as specified above // CAUTION: // it's up to you to make sure the handler receives the correct args, // bunvim doesn't do any validations // print row and col in neovim await nvim.call("nvim_exec_lua", [`print("row: ${row} - col: ${col}")`, []]); // return `true` to remove handler return count++ >= 5; }); // multiple handlers can be registered for the same notification nvim.onNotification("cursor_move", async ([row, col]) => { // replace contents in current buffer lines 1 and 2 await nvim.call("nvim_buf_set_lines", [0, 0, 2, true, [`row: ${row}`, `col: ${col}`]]); }); const channelId = nvim.channelId; // create autocommand to notify our plugin via `vim.rpcnotify` // whenever the cursor moves await nvim.call("nvim_create_autocmd", [ ["CursorHold", "CursorHoldI"], { desc: "Notify on Cursor Move", command: `lua local cursor_pos = vim.api.nvim_win_get_cursor(0) local row = cursor_pos[1] local col = cursor_pos[2] vim.rpcnotify(${channelId}, "cursor_move", row, col)`, }, ]);
nvim.onRequest(request: string, callback: function)
Registers a handler for a specific RPC Request.
Requests must be typed before you declare a handler for them, or TypeScript will complain.
The difference between an RPC Notification and an RPC Request, is that requests block neovim until a response is returned. Notifications are non-blocking.
import { attach, type BaseEvents, type EventsMap } from "bunvim"; import { gracefulShutdown } from "./utils.ts"; // an interface to define your requests and their args interface MyEvents extends BaseEvents { notifications: EventsMap; // default type requests: { // declare custom request: "before_exit", // that would be called with args: [buffer_name: string] "before_exit": [buffer_name: string]; }; } // attach to neovim const nvim = await attach<MyEvents>({ ... }) // register a handler for the request "before_exit" nvim.onRequest("before_exit", async ([buffer_name]) => { // "buffer_name" is of type "string" as specified above // CAUTION: // it's up to you to make sure the handler receives the correct args, // bunvim doesn't do any validations // this should actually never get called, // because this handler gets overwritten below console.log("buffer_name: ", buffer_name); // we must return something to unblock neovim return null; }); // only one handler per request may be registered. // if you call `nvim.onRequest` for an already registered handler, // the older handler is replaced with the new one. nvim.onRequest("before_exit", async ([buffer_name]) => { gracefulShutdown(buffer_name); return null; }); const channelId = nvim.channelId; // create autocommand to call our function via `vim.rpcrequest` // whenever neovim is about to close await nvim.call("nvim_create_autocmd", [ ["VimLeavePre"], { desc: "RPC Request before exit", command: `lua local buffer_name = vim.api.nvim_get_current_buf() vim.rpcrequest(${channelId}, "before_exit", buffer_name)`, }, ]);
nvim.detach()
Closes connection with neovim.
nvim.detach();
nvim.logger
Instance of winston logger. May be
undefinedif logging was not enabled.Used to log data to console and/or file. Does not log/print messages to Neovim.
// log functions sorted from highest to lowest priority: nvim.logger?.error("error message"); nvim.logger?.warn("warn message"); nvim.logger?.info("info message"); nvim.logger?.http("http message"); nvim.logger?.verbose("verbose message"); nvim.logger?.debug("debug message"); nvim.logger?.silly("silly message");
To enable logging to Console and/or File, a logging.level
must be specified when calling the attach method.
const nvim = await attach({
socket: SOCKET,
client: { name: "my-plugin-name" },
logging: {
level: "debug", // <= LOG LEVEL
},
});
nvim.logger?.info("hello world");Bunvim internally logs with logger.debug() and logger.error().
Set logging.level higher than debug to not display bunvim's internal logs when
printing logs for your plugin.
Levels from highest to lowest priority:
- error
- warn
- info
- http
- verbose
- debug
- silly
After setting a logging.level, you can see your logs live with the command bunvim logs and
specifying the client.name you defined in your attach.
In a terminal, run the command:
# this process will listen for logs and print them to the console
# Ctrl-C to stop process
bunx bunvim logs my-plugin-nameFor more information about the CLI tool, run the command:
bunx bunvim --helpYou can also write your logs to a file by specifying a path when calling the attach method:
const nvim = await attach({
socket: SOCKET,
client: { name: "my-plugin-name" },
logging: {
level: "debug", // <= LOG LEVEL
file: : "~/my-plugin-name.log" // <= PATH TO LOG FILE
},
});If you want to log/print a message to the user in Neovim, use:
import { NVIM_LOG_LEVELS } from "bunvim";
await nvim.call("nvim_notify", ["some message", NVIM_LOG_LEVELS.INFO, {}]);
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent