plenary.nvim
A comprehensive Lua library for Neovim providing async utilities, job control, file operations, testing, and more.
What is plenary.nvim?
plenary.nvim is a comprehensive Lua utility library for Neovim, designed to provide plugin developers with a shared set of common functions. It solves the problem of repeatedly writing boilerplate code for tasks like asynchronous operations, file system interactions, process management, and testing.
Neovim plugin developers who need reliable, reusable utilities for building complex plugins without reinventing basic functionality.
Developers choose plenary.nvim because it offers a cohesive, well-integrated suite of utilities specifically for Neovim's Lua environment, reducing development time and ensuring consistency across plugins.
Overview
plenary: full; complete; entire; absolute; unqualified. All the lua functions I don't want to write twice.
Use Cases
Best For
- Writing asynchronous Neovim plugins using coroutines
- Managing system processes from within Neovim
- Performing recursive file scans and path manipulations
- Running isolated tests for Neovim plugins
- Detecting filetypes programmatically
- Creating floating windows and popup interfaces
Not Ideal For
- Standalone Lua projects without Neovim integration
- Production plugins requiring long-term API stability
- Minimalist plugins where lightweight dependencies are preferred
- Developers who only need simple, synchronous file operations
Pros & Cons
Pros
Coroutine-based utilities eliminate callback hell by transforming nested libuv calls into linear code, as shown in the README's file reading example.
Bundles modules for jobs, paths, testing, and more, reducing the need to source multiple libraries for common plugin tasks.
Used by popular plugins like Telescope and Neogit, proving its reliability and integration within the Neovim community.
Offers a busted-style test harness that runs specs in isolated Neovim instances, essential for robust plugin development.
Cons
The README explicitly warns it's 'very much in pre-alpha' with expected API changes, making it risky for production code.
Documentation is sparse, relying on future generators, which can hinder learning and troubleshooting for new users.
Useless outside Neovim due to reliance on its functions, limiting use to plugin development only.
The test harness requires spawning separate Neovim instances, which can be resource-intensive and complex to set up correctly.
Frequently Asked Questions
Related Projects
nui.nvimUI Component Library for Neovim.
lazydev.nvimFaster LuaLS setup for Neovim
sqlite.luaSQLite LuaJIT binding with a very simple api.
one-small-step-for-vimkindDebug adapter for Neovim plugins
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.