Beta stage — active development. This repository is past its first shape and in active use, but the surface is not frozen: breaking changes are still possible. Pin a commit or tag if you depend on it.
_ _ _ _
| (_) |__ _ ____ _(_)_ __ ___
| | | '_ \ | '_ \ \ / / | '_ ` _ \
| | | |_) || | | \ V /| | | | | | |
|_|_|_.__(_)_| |_|\_/ |_|_| |_| |_|
Part of the wkd family — see this plugin's page on the site.
Reusable Lua and Neovim helpers — one tested base under a whole set of plugins.
Extracted from a private Neovim configuration so that personal plugins can
share a single set of helpers as a dependency instead of each carrying its own
copy. It has no third-party dependencies — only vim and itself.
docmap.nvim — reads and navigates the docs this library's conventions produce; it also holds the ecosystem architecture that says what belongs down here.
insights.nvim — static analysis of a project from inside the editor, and the largest single consumer of the helpers here.
runtime-analysis.nvim — the runtime counterpart, measuring what was actually called rather than what the source says.
Every
StefanBartl/*.nvimplugin depends on this one. The direction never reverses: nothing here may require any of them.
Start at the documentation index — lib.nvim describes the
same module at several depths, and the index says which one answers which
question.
- Requirements — Neovim version, and the (lack of) third-party dependencies.
- Installation — plugin dependency vs. config-wide bootstrap.
- Quickstart — requiring a module directly vs. through the aggregator.
- Namespaces & modules — every
lib.lua.*/lib.nvim.*module, one line each, with links to per-module docs. - Design pattern collection — GoF and common modern patterns as reference modules (
lib.lua.patterns.*,lib.nvim.patterns.*) or pointers to the feature module that already is the pattern. - API reference — function signatures across a whole theme, without opening dozens of files.
- Data classes —
lib.nvim.data_classes: may this area or repository leave the machine? Reads the per-deviceareas.jsonof the desktop apps (tasks-desktop) fail-closed; no file, a broken file or no entry isunclassified, released for nothing. - Configuration — the aggregator strategies and their defaults.
- Bindings — the deliberately small user command and autocommand surface, including
:Lib depsand:Lib helptags.
- Features — cross-cutting capabilities, written up per theme: why each exists and when to reach for it.
- Examples — runnable scenarios for the larger modules.
- Guides — ecosystem-wide findings this library absorbed so nobody has to re-solve them.
- Architecture — the
lib.lua.*/lib.nvim.*split and the rule behind it. - Workflow — building a plugin on top: which module for which job.
- Health check — what
:checkhealth libreports. - Contributing — ground rules, repository layout, and how to add a module.
- Templates — resolving
lib.nvimin a dependent plugin's own headless test suite, and the scripts of a plugin's command line (cli_script.lua) and machine contract (contract_host.lua). - Feedback — bugs, feature requests and usage questions; broader discussion in Discussions.
:help lib.nvim is the same reference inside the editor — see
docs/help.md for how the tags are generated.
Not in this repository: ecosystem architecture
— where docs, static analysis and runtime each belong across the four pieces
this library is the bottom of (lib.nvim, docmap.nvim,
runtime-analysis.nvim, mdview.nvim), and the rule that decides what moves
down here and what does not.
lib.nvim is released under the MIT License.
Uses
- docmap.nvim: A developer tool of lib.nvim (
pattern_usage) reads a module map that docmap.nvim made (docmap.core.artifact). (picture) - filetree.nvim: When the popup kit of lib.nvim creates a missing file, it reveals the new file in filetree.nvim, if filetree.nvim is loaded and set up. (picture)
- images.nvim: The image preview of lib.nvim (
image_preview) detects images.nvim as its provider. (picture) - runtime-analysis.nvim: The telemetry wrapper of lib.nvim (
strategies.telemetry_wrap) reports to runtime-analysis.nvim (runtime-analysis.telemetry). (picture) - tasks-desktop: The data classes of lib.nvim come from
areas.jsonin the config folder of tasks-desktop: the same file and schema tasks-hub reads. (picture) - ui.nvim: The popup notifications of lib.nvim use
ui.kit.toastof ui.nvim when it is installed. (picture)
Used by
- ai.nvim: calls it
- buffer-ctx.nvim: calls it
- cascade.nvim: calls it
- cmdlog.nvim: calls it
- color_my_ascii.nvim: calls it
- dap.nvim: calls it
- data.nvim: calls it
- debugging.nvim: calls it
- diff.nvim: calls it
- docmap.nvim: calls it
- emojis.nvim: calls it
- fileops.nvim: calls it
- filetree.nvim: calls it
- github_stats.nvim: calls it
- gitsuite.nvim: calls it
- gopath.nvim: calls it
- hover.nvim: calls it
- images.nvim: calls it
- insights.nvim: calls it
- language.nvim: calls it
- lsp.nvim: calls it
- markdown.nvim: calls it
- mdview.nvim: calls it
- media.nvim: uses it when installed
- open.nvim: calls it
- pdfport.nvim: calls it
- pickers.nvim: calls it
- recommender.nvim: calls it
- replacer.nvim: calls it
- reposcope.nvim: calls it
- rules.nvim: calls it
- runtime-analysis.nvim: calls it
- sandbox.nvim: calls it
- sessions.nvim: calls it
- spotlight.nvim: calls it
- tasks.nvim: calls it
- terminal.nvim: calls it
- testing.nvim: calls it
- ui.nvim: calls it
- every plugin that stands on it (39): ai.nvim, buffer-ctx.nvim, cascade.nvim, cmdlog.nvim, color_my_ascii.nvim, dap.nvim, data.nvim, debugging.nvim, diff.nvim, docmap.nvim, emojis.nvim, fileops.nvim, filetree.nvim, github_stats.nvim, gitsuite.nvim, gopath.nvim, hover.nvim, images.nvim, insights.nvim, language.nvim, lsp.nvim, markdown.nvim, mdview.nvim, media.nvim, open.nvim, pdfport.nvim, pickers.nvim, recommender.nvim, replacer.nvim, reposcope.nvim, rules.nvim, runtime-analysis.nvim, sandbox.nvim, sessions.nvim, spotlight.nvim, tasks.nvim, terminal.nvim, testing.nvim, ui.nvim
