rsplug-0.2.3 is not a library.

rsplug.nvim

A blazingly fast Neovim plugin manager written in Rust

Overview

rsplug.nvim is a modern Neovim plugin manager that takes a different approach: it's implemented as an external Rust binary to build a Vim pack package rather than a Vimscript/Lua plugin. Instead of installing plugins directly, rsplug synchronizes Vim pack packages from TOML configuration files, enabling fast, parallel Git operations, deterministic builds. In the future, rsplug will provide seamless integration with Nix-based workflows.

Why rsplug.nvim?

External binary architecture: Say goodbye to launching Neovim just to manage plugins
Blazingly fast: Parallel shallow Git clones with depth=1 for rapid installation and updates
Deterministic and reproducible: Lock file support ensures consistent plugin versions across machines
Lazy-loading first: Sophisticated lazy-loading system with autocmds, filetypes, commands, and keymaps
Minimal runtime overhead: Merges compatible plugins to reduce Neovim's runtimepath size
TOML configuration: Clean, readable configuration format with version wildcards and dependency support

Quick Start

Installation

First, you need to add one liner to your Neovim configuration.

dofile(vim.fn.expand '~/.cache/rsplug/init.lua')

Then, install the rsplug binary:

From Source

Requires Rust 1.89+ and Git:

git clone https://github.com/gw31415/rsplug.nvim.git
cd rsplug.nvim
cargo build --release
# Binary will be at target/release/rsplug

Using Nix Flakes

nix build github:gw31415/rsplug.nvim
# Binary will be in result/bin/rsplug

Or add to your flake:

{
  inputs.rsplug.url = "github:gw31415/rsplug.nvim";
  # ...
}

Basic Usage

Create a configuration file (e.g., ~/.config/nvim/rsplug.toml):

[[plugins]]
repo = "nvim-lua/plenary.nvim"

[[plugins]]
repo = "neovim/nvim-lspconfig"
on_event = "BufReadPre"
lua_after = """
require('lspconfig').rust_analyzer.setup{}
"""

[[plugins]]
repo = "hrsh7th/nvim-cmp"
on_event = ["InsertEnter", "CmdlineEnter"]
lua_after = "require('cmp').setup{}"

Synchronize plugins from the TOML file:

[!WARNING] rsplug synchronizes pack packages based on the configuration file(s) you provide. If you change which configuration file you specify as an argument, plugins defined in other files will no longer be loaded. Always use the same configuration file pattern or use the RSPLUG_CONFIG_FILES environment variable to ensure consistency.

rsplug -iu ~/.config/nvim/rsplug.toml

[!TIP] Use environment variable for convenience! Instead of specifying the config file every time, set RSPLUG_CONFIG_FILES in your shell profile:

export RSPLUG_CONFIG_FILES="~/.config/nvim/rsplug.toml"
# Or use glob patterns:
export RSPLUG_CONFIG_FILES="~/.config/nvim/plugins/*.toml"
# Run rsplug without positional arguments:
rsplug -iu

CLI Options

To install new plugins: -i or --install

rsplug --install ~/.config/nvim/rsplug.toml
rsplug -i ~/.config/nvim/rsplug.toml

To update existing plugins: -u or --update

rsplug --update ~/.config/nvim/rsplug.toml
rsplug -u ~/.config/nvim/rsplug.toml

To sync hooks or scripts only: (no git operations)
```
rsplug ~/.config/nvim/rsplug.toml
```
To use the lock file for exact versions: --locked
```
rsplug --locked ~/.config/nvim/rsplug.toml
```

Key Features

Lazy Loading

rsplug.nvim provides comprehensive lazy-loading triggers:

[[plugins]]
repo = "nvim-telescope/telescope.nvim"
on_cmd = "Telescope"                    # Load on command
on_map = { n = "<leader>ff" }           # Load on keymap
on_event = "VimEnter"                   # Load on autocmd event
on_ft = ["lua", "vim"]                  # Load on filetype

Lua modules are automatically detected and loaded on require:

[[plugins]]
repo = "nvim-lua/plenary.nvim"
# Will auto-load when you call require('plenary')

Lifecycle Hooks

Execute Lua code / subprocess before/after plugin load or install:

[[plugins]]
repo = "folke/which-key.nvim"
lua_before = "vim.g.which_key_timeout = 300"  # Before plugin loads
lua_after = "require('which-key').setup{}"    # After plugin loads

[[plugins]]
repo = "yetone/avante.nvim"
build = ["make"]                              # Run after install/update
lua_build = "vim.fn.system({'make', 'docs'})" # Run Lua after install/update

Dependencies

Declare plugin dependencies that load together:

[[plugins]]
repo = "nvim-telescope/telescope.nvim"
depends = ["plenary.nvim"]             # Load plenary.nvim simultaneously
on_cmd = "Telescope"

Repository Sources

GitHub (shorthand)

[[plugins]]
repo = "owner/repo"               # Default branch
repo = "owner/repo@main"          # Specific branch
repo = "owner/repo@v1.2.0"        # Exact tag
repo = "owner/repo@v*"            # Latest matching tag (wildcard)

General Git URL

Any repository accessible via git can be specified by providing a full URL containing ://:

[[plugins]]
repo = "https://gitlab.com/owner/plugin"          # Default branch
repo = "https://gitlab.com/owner/plugin@main"     # Branch / tag / commit
repo = "https://codeberg.org/owner/plugin@v1.0"  # Any hosting

The @rev suffix works the same as for GitHub shorthand — it accepts branch names, tags, and wildcard patterns.

The cache directory is derived from the URL's host and path (scheme, authentication, port, and .git suffix are stripped), e.g.:

https://gitlab.com/owner/plugin  →  ~/.cache/rsplug/repos/gitlab.com/owner/plugin

Version Control

Lock to specific versions or use wildcards:

[[plugins]]
repo = "j-hui/fidget.nvim@v1.2.0"      # Exact version

[[plugins]]
repo = "j-hui/fidget.nvim@v*"          # Latest v* tag

[[plugins]]
repo = "j-hui/fidget.nvim@main"        # Specific branch

Lock File for Reproducibility

Every time you run rsplug a lock file is generated at ~/.cache/rsplug/rsplug.lock.json by default. This file records the exact commit hashes of all installed plugins.

To sync plugins the exact versions from the lock file, use the --locked flag:

rsplug --locked

Multiple Configuration Files

Combine multiple configuration files using glob patterns:

rsplug '~/.config/nvim/plugins/*.toml'
# Or with multiple patterns:
rsplug '~/.config/nvim/base.toml:~/.config/nvim/plugins/*.toml'

Or set via environment variable:

export RSPLUG_CONFIG_FILES="~/.config/nvim/plugins/*.toml"
rsplug

Configuration Reference

Plugin Fields

Field	Type	Description
`repo`	String	`owner/repo[@rev]` (GitHub) or any Git URL (`https://…[@rev]`)
`start`	Boolean	If `true`, always load at startup (default: `false`)
`on_event`	String/Array	Autocmd event(s) to trigger lazy-load
`on_cmd`	String/Array	User command(s) to trigger lazy-load
`on_ft`	String/Array	Filetype(s) to trigger lazy-load
`on_map`	String/Table	Keymap(s) to trigger lazy-load
`depends`	Array	Plugin dependencies loaded simultaneously
`lua_start`	String	Lua code to run at Neovim startup
`lua_before`	String	Lua code to run before plugin loads
`lua_after`	String	Lua code to run after plugin loads
`build`	Array	Subprocess to run after install/update
`lua_build`	String	Lua script to run after install/update
`name`	String	Custom plugin name (default: repo name)
`sym`	Boolean	Use symlink instead of file copy
`ignore`	String	Gitignore-style patterns for files to exclude

Key Mapping Syntax

# Simple (`nxo` modes)
on_map = "<leader>f"

# Single mode
on_map = { n = "<leader>f" }

# Multiple modes
on_map = { nx = "<leader>f" }

# Multiple keys
on_map = { n = ["<leader>f", "<leader>g"] }

Command-Line Interface

Vim plugin manager written in Rust

Usage: rsplug [OPTIONS] <CONFIG_FILES>...

Arguments:
  <CONFIG_FILES>...  Glob-patterns of the config files. Split by ':' to specify multiple patterns [env: RSPLUG_CONFIG_FILES]

Options:
  -i, --install              Install plugins which are not installed yet
  -u, --update               Access remote and update repositories
      --locked               Fix the repo version with rev in the lockfile
      --lockfile <LOCKFILE>  Specify the lockfile path
  -h, --help                 Print help

How It Works

rsplug.nvim operates in two phases:

1. Build Phase (CLI)

rsplug synchronizes the pack packages from your TOML configuration:

Parses TOML configuration file(s)
Resolves plugin dependencies using DAG (Directed Acyclic Graph)
Clones/updates Git repositories to ~/.cache/rsplug/repos/

Clone new plugins if it provided the option --install
Update repos if it provided the option --update
Synchronizes to specific commit from lock file if --locked is provided

Writes lock file with exact commit hashes
Runs build commands / lua_build scripts if specified
Generates ~/.cache/rsplug/init.lua, writes the generated control plugin under ~/.cache/rsplug/pack/_gen/opt/, and stores that generation's manifest.json inside the control plugin

Important: The pack directory reflects exactly what's in your current configuration file(s). If you change which configuration file you pass as an argument, the pack directory will be re-synchronized to match only those plugins.

2. Runtime Phase (Neovim)

~/.cache/rsplug/init.lua prepends the generated packpath and explicitly packadds the current generated control plugin
lua_start scripts run at startup before controlled startup plugin loads
start = true plugins are placed under pack/_gen/opt/ and loaded during startup via rsplug's controlled :packadd! path
Registers lazy-loading triggers (autocmds, commands, keymaps)
On startup or lazy trigger, loads plugin via :packadd with before/after hooks

v0.2.0 Breaking Change

rsplug v0.2.0 changes the Neovim bootstrap line and the generated package layout so start = true plugins can run lua_before and lua_after deterministically.

Update your init.lua from:

vim.opt.packpath:prepend("~/.cache/rsplug")

to:

dofile(vim.fn.expand("~/.cache/rsplug/init.lua"))

Managed plugins, including start = true plugins, are now placed under pack/_gen/opt/ and loaded by rsplug's generated runtime.

To preserve deterministic lua_before / lua_after ordering, managed start = true plugins are not merged with other managed startup plugins.

Advanced Topics

Plugin Merging

rsplug automatically merges plugins with the same lazy-loading trigger when their files don't conflict. This reduces runtimepath size and improves startup performance.

Build Caching

Build commands are cached using a hash of:

Git commit SHA
Working directory changes
Build command itself (build and lua_build)

Rebuilds only occur when necessary, speeding up subsequent runs.

Startup Generation Manifests

rsplug writes the generated control plugin under pack/_gen/opt/<hash>/ and loads the current control plugin from init.lua with :packadd <hash>. Older retained control plugins are not native startup packages, so they are not loaded by packloadall or startup package scanning.

Each control plugin contains a manifest.json listing the shared _gen entries that generation references. The runtime exposes this data as _rsplug.manifest. rsplug keeps the latest few control manifests and only cleans _gen plugin directories when no retained manifest references them. This avoids deleting Lua hook/runtime modules still referenced by a Neovim instance that started before a later rsplug update.

Who Is This For?

rsplug.nvim is ideal for:

Advanced Neovim users who want precise control over plugin loading
Performance enthusiasts seeking fast startup times
Rust developers who prefer Rust tooling
Configuration hackers who enjoy TOML over Lua for data

Documentation

Quick reference: This README
Detailed documentation: :help rsplug (see doc/rsplug.txt)
Example configuration: See example.toml in this repository
Repository: https://github.com/gw31415/rsplug.nvim

Known Limitations

Plugin merging may occur between sibling dependencies without clear ordering control

Contributing

Issues and pull requests are welcome! See the issue tracker for current tasks and known issues.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Note: This is an early-stage project under active development. APIs and behaviors may change.

rsplug 0.2.3