My background isn’t the typical path to becoming a software engineer. I didn’t study computer science. Instead, I earned both a bachelor’s and a master’s degree in Renewable Energy Systems from HTW Berlin. Somehow, that journey led me to become a professional Haskell developer, building distributed power management and delivery systems.

In Europe, the tech job market is dominated by object-oriented languages like Java and C#. Meanwhile, Haskell remains a relatively niche language, often associated with blockchain and finance. Yet, in my experience, Haskell is a perfect fit for the complexities of renewable energy technology, an area that could greatly benefit from the power of functional programming.

In this article, I’ll share my journey into Haskell and explain why I believe it has untapped potential in the renewable energy sector, despite its limited presence in the mainstream job market.

Don’t panic about thermodynamics

During my university years, thermodynamics and energy process engineering were notorious among students. The courses were packed with daunting formulas - far too many to memorize, and far too complex to reference in the heat of an exam.

But one piece of advice from our professor changed everything for me. She encouraged us to truly understand the international system of units (SI), especially by practicing how to juggle and decompose them into their seven base units¹.

For instance, one can break down the unit Watt (power) into its base components: kilogram, metre, and second (W = kg · m² / s³). With this trick, I could solve problems by letting the units guide me, rather than relying on rote memorization. I minimized what I needed to write down and found myself finishing exams with plenty of time to spare, and scoring perfectly every time.

What I didn’t realise at the time, was that this mindset of letting structure and units guide my reasoning was strikingly similar to type-driven development, a concept I’d only discover years later.

Flexible systems, fragile scripts

Early on during my studies, I started working part-time in one of my university’s research groups. On my first day, I was handed a MATLAB book and, after a week of self-study, began contributing to the development of simulation models and control algorithms for solar storage systems.

These models and algorithms are especially important for renewable energy systems. While traditional fossil power sources tend to be sluggish and operate in predictable, steady ways, renewables are inherently variable. They thrive when supported by flexibility and intelligent control.

The code we wrote was anything but pretty. For example, here’s a function we published that simulates an AC-coupled lithium-ion battery:

function [Ppv, Pbat, Ppvs, Pbs, Pperi, soc] = PerModAC(s, sim, pvmod, Pl, ppv)

SOC_h = s.SOC_h; % Hysteresis threshold for the recharging of the battery
P_AC2BAT_DEV = s.P_AC2BAT_DEV; % Mean stationary deviation of the charging power in W
P_BAT2AC_DEV = s.P_BAT2AC_DEV; % Mean stationary deviation of the discharging power in W
% ...

I won’t get into too much detail, but the main issue with scripting languages like Python or MATLAB quickly became apparent:

In this example, the argument ppv is expected to be a vector containing the normalized DC power output of the PV generator in kW/kWp².

However, nothing stops the caller of this function from passing in anything they want - even a string. And, dare I say, I’m quite confident that I have never met a MATLAB programmer who knows what a unit test is. Our approach to testing involved generating graphs and comparing them qualitatively with measured data. This process is both time-consuming and error-prone, and it only proves effective if done frequently and validated thoroughly. It relies heavily on human effort rather than leveraging the assistance of automated tools. Without proper safeguards in place, small errors can easily go unnoticed, resulting in fragile code and more difficult troubleshooting.

Why traditional OOP falls short

My first full-time job was writing simulation software for sector-coupled renewable energy systems in Java. Having a compiler that provides some type safety was a huge improvement over my prior MATLAB experiences. To compare, a simulation model for a battery might look something like this³:

public class ACBattery {
  ACBatterySpec spec;
  // Energy content in watt-hours
  double energyWh;

  // Constructor omitted for brevity

  /**
  * @param powerW - The charging power in watts
  * @param durationS - The duration in seconds
  */
  public void charge(double powerW, double durationS) {
    // Implementation omitted for brevity
  }
}

While callers can no longer pass in completely wrong types, two major issues remain:

1. The units are encoded in the variable names.
2. Both arguments of the charge function are semantically different, but they have the same type.

A third issue is that object-oriented languages are designed to be stateful, which causes difficulty with concurrency and makes testing very challenging.

This approach is not expressive enough to prevent someone from passing in a value with the wrong unit, or from misusing the arguments in the implementation. As a result, unit tests must be written just to compensate for this lack of type safety.

Technically, it’s possible to define types for each argument: For example, consider using the unit-api library to encode units:

public class ACBattery {
  ACBatterySpec spec;
  Quantity<Energy> energy;

  // Constructor omitted for brevity

  /**
   * @param power Charging power
   * @param duration Charging duration
   */
  public void charge(Quantity<Power> power,
                     Quantity<Time> duration) {
    Quantity<Energy> energyAdded =
      power.multiply(duration).asType(Energy.class);
    this.energy = this.energy.add(energyAdded);
  }
}

This approach is more robust:

• You cannot accidentally pass a length or temperature where a power or time is expected.
• The compiler will prevent you from trying to compose incompatible units.

But in a language like Java, this comes at a cost:

• It means object allocation, runtime conversions and dynamic dispatch, which can introduce significant performance costs.
• Instead of using basic arithmetic operators (+, -, *, …), you now have to use redefined functions (add, multiply, etc.).

Not to mention a significant increase in verbosity / boilerplate you must maintain. That harms the one thing business cares about: developer productivity.

In my experience working across multiple Java codebases, all of them ultimately relied on primitives for physical quantities, sacrificing safety for simplicity and speed.

Type-Driven Development: The Haskell advantage

Having previously reaped the benefits of letting units guide my reasoning, it didn’t take long for me to start exploring whether type systems could offer the same reliability. About five years ago, I taught myself Haskell, and a year later joined my current employer, who gave me the opportunity to use it professionally in the renewable domain I’m so passionate about.

In Haskell, types are a rigorous framework for representing real-world constraints directly in code. Here’s how the same charge function’s type signature might look, using Haskell’s dimensional library, which “provides statically-checked dimensional arithmetic for physical quantities, using the 7 SI base dimensions”:

data ACBattery num
  = ACBattery
  { spec :: ACBatterySpec
  , energy :: Energy num
  }

charge :: Fractional num => Power num -> Time num -> ACBattery num -> ACBattery num
charge power time battery = -- Implementation omitted for brevity

If you’re unfamiliar with a functional language like Haskell, this might look cryptic. But bear with me - let’s break it down:

• The function uses a type constraint, Fractional num, which lets the caller specify the underlying numeric representation. For example, num could be Double for floating-point, or something more precise like Pico or Milli for fixed-point.

A less generic version of this function might look like:

charge :: Power Double -> Time Double -> ACBattery Double -> ACBattery Double
charge power time battery = -- Implementation omitted for brevity

• The first and second arguments are the power we supply to the battery and the amount of time we supply it for.

• The third argument, ACBattery, is the battery’s current state. Haskell is stateless by design, so the (immutable) state is passed in, and a new state is returned, making reasoning about code and testing much simpler.

• The final -> ACBattery num means the function evaluates to the battery’s updated state after charging.

Notice the absence of error-prone, manual unit conversions, or units in the variable names? This aligns perfectly with the Parse, don’t validate principle. By encoding expectations in the types, you ensure that only correctly-formed data enters your core logic. Once data are parsed into these types, you don’t need to check them at runtime, they’re guaranteed by the compiler.

Let’s simplify the function even further, focusing on just energy transformation:

charge :: Power Double -> Time Double -> Energy Double -> Energy Double
charge power time energy =
    energy + power * time

Instead of a battery state, this version takes the battery’s energy before charging and evaluates to the energy after charging.

Unlike in Java, where using units libraries requires verbose method calls like add and multiply, we can use our familiar arithmetic operators directly. Another advantage is that because dimensional uses Haskell’s newtype declarations, each quantity is represented internally as its underlying numeric type. This means that, at runtime, we can expect negligible overhead compared to plain numeric operations⁴ - unlike Java’s units libraries, which rely on object allocation and dynamic dispatch.

When calling the charge function, you specify the units directly:

example = charge chargingPower duration currentEnergy
  where
    chargingPower = 1 *~ kilo Watt
    duration = 30 *~ second

The dimensional library ensures that only compatible quantities can be composed. If you accidentally swap arguments or use the wrong operation, you won’t get mysterious runtime bugs, you’ll get a clear, immediate type error:

If I multiply power * time instead of trying to divide, the error disappears, because the units align. It feels almost magical: Haskell’s type system, together with dimensional, lets the compiler guide you toward correct implementations. Unit safety, domain modeling, and strong typing aren’t just academic. They’re practical tools for building reliable, maintainable software in renewable energy and beyond.

All this time I had no idea: My thermodynamics professor had taught me that Haskell is the perfect fit for renewable energy tech!

Test-Driven Development: Focus on what matters!

I’m a strong advocate for test-driven development (fake it till you make it). In my experience, it’s the best way to ensure high-quality, meaningful test coverage. One major reason people avoid TDD is that it can seem tedious, especially in traditional OOP, where unit tests often compensate for weak type safety. With Haskell, we can write tests that catch far more bugs with far less code, by focusing on what matters: properties and behaviour.

Powerful libraries like QuickCheck, and its integration with frameworks such as tasty-quickcheck, allow you to express and test mathematical properties directly, rather than writing tests for specific cases or edge conditions.

Here’s a hypothetical example:

chargingTest :: TestTree
chargingTest = testGroup "Charging"
  [ testProperty "does not exceed maximum capacity"
      \(Positive duration) (Positive power) (Small energyDelta) ->
        let previousState =
              testBattery { energy = maxCapacity testBatterySpec - abs energyDelta }
            newState = charge power duration previousState
            newEnergy = energy newState
        in newEnergy <= maxCapacity testBatterySpec
  , testProperty "does not exceed nominal AC charging power"
      \(Positive duration) (NonNegative deltaPower) (NonNegative energy) ->
        -- Implementation omitted for brevity
  -- ...
  ]

With property-based testing, the framework generates a wide variety of (pseudo-)random inputs for you, so you don’t have to hand-craft edge cases. This approach lets you verify that your code upholds the core invariants and physical laws of your domain, rather than just checking a handful of examples.

Credits

Thanks to Alex Drake (who I hack on Haskell clean tech with in our free time) for proof-reading.

Discuss

• HackerNews
• Haskell discourse
• Reddit

A few months ago, I posted an introduction to Lux, a modern package manager for Lua that treats Neovim and Nix as first-class citizens and is compatible with the LuaRocks ecosystem.

We have a few updates to share.

Lumen Labs

Up until recently, we had been working under a temporary GitHub org: nvim-neorocks.

We have now formalized as a proper open-source organization. You can find us under the name “Lumen Labs” (definitely not an evil corporation). If you resonate with our mission, we’ve also set up an OpenCollective.

We aim to up our transparency with more blog posts, a higher rater of public announcements and status updates, and more.

Luanox

A frequent question we received when we announced Lux was: “Why is it not written in Lua?”¹

Well, NTBBloodbath and Vhyrro have been writing lots of Elixir to build Luanox, a work-in-progress modern hosting site for Lua packages, in the spirit of crates.io or PyPI.

Waiting on luarocks.org to return a massive manifest file, just so we can check if a single package exists, is taking up about 50 % of Lux’s runtime for basic package management operations. For this reason, we wanted to create something snappy, secure and new, while still retaining compatibility:

• Licensed under AGPL-3.0.
• No storage of persistent information that could be leaked (no passwords; stateless JWT tokens).
• A custom service that runs in a separate container and verifies that rockspecs do not do anything malicious.
• Immutable packages².
• Uses OpenAPI.
• On the roadmap: 2FA for package uploads and facilities for recovering from an account takeover.

The site itself doesn’t store any persistent information that could be leaked.

We’re currently hosting a beta version of the site over at https://beta.luanox.org. On the Lux side, we’re also working on integrating the site so people can start uploading test packages there! Once we’re confident in the site’s performance, we’ll move all the data over to the final product.

In the meantime, feel free to try making an account. Beta users will get a special badge in the final release :D

Lux updates

With the help of users, who have been rigorously testing and contributing to Lux, we’ve squashed many bugs and significantly upped compatibility with luarocks packages.

Some notable new features since the previous announcement:

• Lux is now licensed under LGPL-3.0-or-later.
• Static type checking based on LuaCATS annotations, powered by emmylua-analyzer-rust. With knowledge of your project’s dependencies, lux-cli can generate a .luarc.json for use by the type checker and a language server.
• A busted-nlua test backend for easily running busted tests with Neovim as the Lua interpreter.
• For packages that haven’t been released to luarocks yet, the lux.toml format now lets you specify Git dependencies.
• A templating system that lets you configure how Lux injects source and version information into generated rockspecs.
• We now publish pre-built binary artifacts for:
  • Arch Linux (via the AUR)
  • Debian
  • AppImage (Linux)
  • macOS (arm64)
  • Windows (x64, MSVC)
  All binary packages come bundled with the lux-lua bindings API for all supported Lua versions.

Our next steps

Ecosystem support in Luanox

Our project was born out of efforts to start pushing luarocks adoption in the Neovim ecosystem. One complaint we’ve heard about this from the community is that uploading Neovim-only packages to a generic Lua registry feels weird. For this reason, we will be adding special concepts that will make publishing Neovim plugins to a central Lua registry feel less “hacky” and more deliberate. We’ll be revamping luarocks’s old concept of manifests and turning them into an easy way to distinguish Lua packages specifically built for a given platform (Neovim, Nginx, etc.), with dedicated search pages just for those manifests! We are also working on a dedicated compatibility layer to make the luarocks CLI also work with Luanox :)

Lux and lux.nvim

On the Lux side, we will update Lux to use Luanox as its main server, falling back to luarocks.org for now. Due to a LuaJIT bug, our lux.nvim rewrite of rocks.nvim is unfortunately on hold while we wait for luarocks.org to support serving zipped JSON manfiests. But we will pick it up again as soon as possible!

Thank you

We’d like to express our heartfelt gratitude for all the tremendous support we have received in making Lua better for everyone. Thanks to the OpenCollective donations we’ve now been able to purchase a dedicated domain. And without all of the bug reports and external contributions, Lux wouldn’t even be close to where it is now!

It’s time Lua got the ecosystem it deserves!

For a bit over a year, we have been cooking up Lux, a new package manager for creating, maintaining and publishing Lua code. It does this through a simple and intuitive CLI inspired by other well-known package managers like cargo.

Today, we feel the project has hit a state of “very usable for everyday tasks”¹.

Features

• Fully portable between systems.
• Parallel builds and installs. 🚀
• Handles the installation of Lua headers² for you. Forget about users complaining they have the wrong Lua headers installed on their system. All you need to do is specify compatible lua versions.
• A fully embeddable lux-lib crate, which can even be built to expose a Lua API.
• Has an actual notion of a “project”, with a simple governing lux.toml file.
  • Uses the lux.toml to auto-generate rockspecs. Say goodbye to managing 10 different rockspec files in your repository. 🎉
• Powerful lockfile support.
  • Fully reproducible builds and developer environments.
  • Source + rockspec hashes that can be used to make Lux easy to integrate with Nix.
• Integrated code formatting (lx fmt) and linting (lx check) powered by stylua and luacheck.
• Native support for running tests with busted.
  • Including the ability to use Neovim as a Lua interpreter.
  • Sets up a pure environment.
• Compatible with the luarocks ecosystem.
  • In case you have a complex rockspec that you don’t want to rewrite to TOML, lux allows you to create an extra.rockspec file, so everything just works.
  • Need to install a package that uses a custom luarocks build backend? Lux can install luarocks and shell out to it for the build step, while managing dependencies natively.

Motivation

Lua

While extensive, Luarocks carries with it around 20 years of baggage, which makes it difficult to make suitable for modern Lua development, while retaining backward compatibility.

With Lux, we’re pushing for a fresh start:

• A notion of a project:
  • With TOML as the main manifest format, you can easily add, remove, pin and update dependencies using the CLI.
  • If you’re in a project directory (with a lux.toml), commands like build will build your project, and install it into a project-local tree.
  • Building will produce a lockfile of your project’s dependencies, allowing you to reproduce your exact dependencies on any compatible system.
• Enforced SemVer: Luarocks allows for arbitrary versions after the patch version. For example, 1.0.1.0.0.0.2 is considered valid by Luarocks, but it has no useful meaning. Lux will parse this too, but will treat everything after the patch version as a prerelease version. We made this decision because we want to encourage package maintainers to stick to SemVer for their releases.
• Parallel builds: Inspired by the Nix store, Lux hashes³ install directories to prevent package conflicts and enable highly parallel builds without risking file system corruption.

Neovim

Thanks to our Neovim plugin manager, rocks.nvim, and the later addition of Luarocks support to lazy.nvim, Luarocks has been steadily gaining popularity in the Neovim space as a way of distributing plugins. But it’s been heavily held back by not being fully portable and by being unpredictable from system to system. Because Luarocks is written in Lua, installing a large number of packages and synchronising plugins with rocks.nvim has been painfully slow.

With Lux, we hope that plugins will start treating themselves as Lua projects. Using Lux is non-destructive and doesn’t interfere with the current way of distributing Neovim plugins (which is via git).

In fact, Lux has a --nvim flag, which tells it to install packages into a tree structure that is compatible with Neovim’s :h packages.

Nix

If a Neovim plugin exists as a Luarocks package, nixpkgs will use it as the source of truth. This is mainly because with a proper package manager, the responsibility of declaring dependencies is the responsibility of the package author. However, Luarocks has very basic lockfile support, which does not include source hashes. While Luarocks (as does Lux) supports conflicting dependencies via its luarocks.loader, nixpkgs cannot reasonably add multiple versions of the same dependency to its package set. Lux’s lux.lock, stores source and rockspec hashes of each dependency. If the source URL is a git repository, lux will store a NAR hash. This means the a lux.lock can be used to create a fixed-output derivation with all dependencies, just as you can do with a Cargo.lock.

Next steps

Right now, our priorities are set on squashing bugs and improving error messages. Soon, we’ll be rewriting rocks.nvim to use Lux instead of Luarocks under the hood. This should let rocks.nvim catch up with other plugin managers in terms of speed and make it endlessly more stable than before. If the rewrite is successful, then that spells great news for the Neovim ecosystem going forward, as it means that Lux can be embedded in other places too (e.g. lazy.nvim, which has had troubles with luarocks in the past)!

Documentation

If you’d like to jump on the Lux train early, head over to our documentation website. A tutorial as well as guides can be found on there.

If you have any questions or issues, feel free to reach out in the GitHub discussions or our issue tracker. Cheers! :)

The Lux Team

License

• Lux is licensed under LGPLv3.0+.
• The Lux logo © 2025 by Kai Jakobi is licensed under CC BY-NC-SA 4.0.

One and a half years ago, I published a post with a call to action to publish Neovim plugins to luarocks. Since then, a lot has happened.

The nvim-neorocks organisation has grown and produced rocks.nvim, which pioneers luarocks support in Neovim, treating luarocks packages as first-class citizens. A lot of plugins are now available on luarocks.org, and publishing plugins that aren’t yet available has never been easier.

I’d like to take some time to provide an update on some recent developments…

The path to nvim-treesitter 1.0

One of my favourite things about Neovim is how easy it is to do exceptionally cool things with tree-sitter. For those new to the concept, tree-sitter is a parsing library that can be used to provide fast and accurate syntax highlighting, code navigation, and much more.

My very first Neovim plugin was a Haskell adapter for neotest, which uses tree-sitter queries to interact with test suites within Neovim, providing diagnostics for tests, among other things.

However, even though nvim-treesitter has been around since early 2020, as of writing this post, its readme still has the following notice:

Warning: Treesitter and nvim-treesitter highlighting are an experimental feature of Neovim. Please consider the experience with this plug-in as experimental until Tree-Sitter support in Neovim is stable!

A roadmap to stability

Over the past year, development has accelerated, and there now exists a roadmap for a stable version 1.0.

The plugin is being rewritten¹ to completely drop the module framework.

Instead, it will only manage parser and query installations. This means that when you install nvim-treesitter 1.0, you won’t have any queries on the runtimepath unless you install a matching parser. Many plugins that used to depend on the legacy module system are now standalone plugins, requiring only the parsers.

Practical example

Typically, a plugin that depends on a tree-sitter parser will indicate its dependency on nvim-treesitter in its documentation. For instance, here are the lazy.nvim install instructions for markdown.nvim:

{
    'MeanderingProgrammer/markdown.nvim',
    main = "render-markdown",
    opts = {},
    name = 'render-markdown', -- Only needed if you have another plugin named markdown.nvim
    dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-tree/nvim-web-devicons' },
}

Interestingly, this plugin doesn’t actually depend on nvim-treesitter. Did you know that you don’t even need nvim-treesitter to install parsers?

A quick dive into :TSInstall

Let’s take a look at how nvim-treesitter manages parsers and queries. On the master branch, which still has the legacy module system, queries for basic functionality, such as highlights (+ injections), folds, indents, are present on the runtimepath, in nvim-treesitter’s queries/<lang>² directory.

As mentioned earlier, this will change with version 1.0 (and you can test-drive it today with Neovim nightly on the main branch). Queries will be in a runtime/queries directory, so they won’t be added to the runtimepath until you install the parser. The plugin locks compatible parser revisions in a lockfile.json. And the nvim-treesitter CI only updates a parser’s revision if the automated tests for the matching queries don’t break. This minimises the risk that queries stop working when you update nvim-treesitter and the installed parsers. Of course, the effectiveness for any given parser depends on how well its queries are tested.

When installing a parser, nvim-treesitter delegates to tree-sitter-cli, which may in turn delegate to a C compiler. Some parsers need to be generated from a grammar.js file, which requires Node.js.

With much of the heavy lifting having recently been moved from nvim-treesitter to tree-sitter-cli, installing parsers has become a lot less error-prone.

However, setting up the correct toolchain can still be a PITA on some platforms.

And there’s one pain point that cannot be solved by keeping track of compatible parsers in a lockfile…

Challenges with downstream plugin compatibility

In March 2024, the tree-sitter-haskell parser underwent a complete rewrite. This significant update brought many improvements but also broke compatibility with several downstream plugins, including:

• nvim-treesitter
• neotest-haskell
• haskell-snippets.nvim
• vim-matchup
• iswap.nvim
• rainbow-delimiters.nvim
• haskell-scope-highlighting.nvim
• nvim-treesitter-context
• nvim-treesitter-textobjects
• tailwind-sorter.nvim

Synchronizing updates across all these plugins to ensure a seamless transition for users is nearly impossible, especially given the limited number of maintainers for these queries.

Immediate impact on users

Until all downstream plugins have been updated, affected users are left with two primary options:

• Pinning nvim-treesitter: Users can pin nvim-treesitter to a version or revision that installs the old version of the parser. Unfortunately, this workaround means they cannot benefit from any other parser updates or fixes. Consequently, users may have to pin plugins that depend on other parsers, delaying overall ecosystem improvements.
• Disabling plugins: This approach ensures users can still receive updates for other parts of their setup but at the cost of losing functionality provided by the disabled plugins.

Wouldn’t it be neat if you could pin parsers individually?

Enter rocks.nvim

For a while, we (the nvim-neorocks team) have been using the Neovim User Rock Repository (NURR) to automatically package many Neovim plugins for luarocks, to be used with rocks.nvim.

Aside from workflows that publish Neovim plugins, we’ve also added a workflow that publishes tree-sitter parsers, bundled with the matching nvim-treesitter queries, to luarocks.org. To top it off, our rocks-binaries project periodically pre-builds the parsers on Linux, macOS (x86_64 + aarch64) and Windows, so that rocks.nvim users on those platforms don’t have to worry about installing any additional toolchains.

Recently, we’ve started publishing the parsers to the root manifest with 0.0.x versions³, where x increments every time the revision changes in the nvim-treesitter lockfile, or whenever the parser’s queries are modified⁴.

With luarocks packages as first-class citizens in Neovim, this allows plugin authors to add parsers as dependencies to their luarocks packages and has a neat side effect: rocks.nvim users can now pin each parser individually.

Welcome to a new era of flexibility and stability!

IMPORTANT

If you use rocks.nvim and run into issues with tree-sitter parsers, please bug us, not the nvim-treesitter maintainers! We provide a rocks-treesitter.nvim module for highlighting and auto-installing parsers, as well as a nvim-treesitter-legacy-api rock that provides the module systems for plugins that still depend on it, without adding queries that could be out-of-sync with the luarocks parsers to the runtimepath.

Note for plugin authors

While luarocks supports loading multiple versions of the same lua dependency, this does not translate to tree-sitter parsers. Neovim will use the first parser it finds on the runtimepath. For this reason, we currently don’t recommend that plugin authors pin parser dependencies. You should leave that up to your users for now.

In the ever-evolving Neovim plugin ecosystem, the usage and appropriateness of a setup function for initializing plugins has become somewhat a hot topic. This discussion has sparked differing opinions among plugin developers.

Like some other plugin authors, I’ve recently found myself reverting back to the more traditional Vim convention of employing vim.g.<namespaced_table> or vim.g.<namespaced_option> for configuration, and leaning on the inherent mechanisms of Neovim for initialization.

In this post, I aim to unpack my perspective on this debate, considering both the present landscape and the potential trajectory of the Neovim plugin ecosystem.

Drawing parallels: The design journey of my first Neovim plugin

While haskell-tools.nvim wasn’t technically my first Neovim plugin, it holds the distinction of being the first that wasn’t merely an adapter or extension for another. If the name resonates with you, it’s likely because I drew inspiration from the popular rust-tools.nvim. Both plugins, though tailored for different programming languages, share a parallel purpose.

rust-tools, for historical reasons, depends on nvim-lspconfig. It relies on a setup function to kickstart the lspconfig.rust_analyzer.setup, among other things. As I was relatively new to Lua and Neovim plugin development, this structure felt like a logical blueprint for haskell-tools. Which led to this module:

local M = {
  config = nil,
  lsp = nil,
  hoogle = nil,
  repl = nil,
}

function M.setup(opts)
  -- initialization omitted for brevity
end

return M

As a Haskell developer, seeing state - initialized with nil - was profoundly unsettling. Despite my reservations, the setup paradigm was omnipresent in most Lua plugins I was using. So I decided to go along with it. This, as @HiPhish puts it very well, was cargo cult programming.

Tracing the origins of setup

Neovim embraced Lua as a first-class citizen with version 0.5. Though the initial API wasn’t as powerful as the one we enjoy today, it marked the onset of an explosive growth in Lua plugins. However, the roots of the setup pattern trace back even earlier. Neovim contributor @norcalli introduced a library designed “to standardize the creation of Lua based plugins in Neovim.”, almost a year before Lua’s elevated status¹.

From this effort, setup was born:

• Plugins shouldn’t use the api unless the user explicitly asks them to by calling a function.
  • For one time initialization for a plugin, this is achieved by having a setup() function which will do any initialization required unrelated to key mappings, commands, and events.
  • Every other call should be encapsulated by functions exported by the plugin.

Observant readers may notice a subtle difference between the foundational approach and the conventions that are prevalent today. In @norcalli’s blueprint, configuration and initialization were decoupled, with an export function designated for configuration and setup exclusively managing initialization. In contrast, many of today’s plugins meld these two by passing a configuration table directly to setup. We will revisit this later on…

Neovim 0.7 - Lua everywhere!

Remember, this setup concept originated before Lua’s deep integration in Neovim. Well before init.lua and auto-loading Lua files on the runtimepath arrived with version 0.7. This version brought with it many improvements to the Lua API. And it was a few months after the release of Neovim 0.7 that @mfussenegger posted an article which made me realise I had stuctured my haskell-tools plugin wrong.

His article (which I strongly recommend reading) differentiates between global and filetype-specific plugins. For Lua plugins, he presents some advantages and disadvantages of various structuring approaches and two configuration methods:

• A setup function, which is “useful if the plugin performs expensive initialization or if what it initializes depends on the configuration”, but forces users to require the plugin, which may impact startup if not managed properly.
• A single global configuration table, like vim.g.foobar_settings, which omits the need for a require, and provides direct access across multiple modules, but may be harder to validate.

haskell-tools redesigned

Continuing the trajectory of Neovim 0.7’s advancements, filetype.lua, emerged as a notable (experimental) addition. By the time Neovim 0.9 rolled around, it had effectively replaced the older filetype.vim. Initially, haskell-tools.setup employed autocommands for Haskell and Cabal files. This approach could bog down startup times, especially if multiple plugins adopted it. Addressing this, I rolled out the start_or_attach function for more efficient initialization, tailored for lazy invocation within users’ after/ftplugin/<haskell|cabal>.lua scripts. This shift also severed the plugin’s tie to nvim-lspconfig for LSP tasks. But, in a nod to backward compatibility, the original setup function remained, bringing along its inherent codebase intricacies.

After recent consideration, I have finally decided to release version 2 of haskell-tools.nvim.

The pitfalls of setup

@mfussenegger clarifies in his article that he does not advocate against a setup function. While I think his article is a great read, I have personally come to the conclusion that setup as we know it must burn. Here’s why…

A false sense of “consistency”

The most common argument I hear in favour of defaulting to setup is “consistency”. In fact, today’s most popular Lua plugin manager, lazy.nvim, defaults to calling require(MAIN).setup(opts) in the absence of a config option. But as we’ve delved into before, the term “setup” is used ambiguously across plugins. For instance, while plugins like nvim-treesitter and telescope.nvim lean on Neovim’s inherent initialization and employ setup solely for configuration, others like nvim-cmp and nvim-lspconfig use the same term for both roles. This facade of uniform naming masks its varied functionalities, leading to false consistency.

Furthermore, global configuration variables or tables, prefixed with a namespace specific to the plugin, are both consistent and compatible with Vimscript².

The mirage of setup-driven expectations

The setup convention in Neovim plugins has inadvertently set certain expectations among users. A notable interaction I had with a user when I decided to remove it from haskell-tools.nvim showcased this: the absence of a familiar setup function made the configuration feel “strange” and “out of place” to them. Further, they worried it would prevent them from conditionally loading or initializing the plugin.

This sentiment points to a broader issue. The prevalent use of the setup function has conditioned users to expect it as a standard for configuring and initializing plugins. This expectation can overshadow alternative, and sometimes more flexible, configuration methods.

Neovim itself offers built-in mechanisms for conditional plugin loading, and many plugin managers support similar functionalities. However, the ubiquity of the setup convention might be inadvertently limiting our view and adaptability, leading us to perceive deviations as anomalies, even when they may offer superior flexibility.

require-ing plugins at startup can break your config

To create robust plugins, it’s imperative to differentiate between configuration and initialization. This becomes particularly crucial when plugins have interdependencies. Careless require calls during the configuration phase can induce unexpected hiccups, primarily influenced by the order of initialization. The best practice? Make such calls deferred or lazy.

Let’s illustrate with an example:

Not ideal

-- May fail if foo is not initialized
-- before lspconfig
local bar = require('foo').bar
require('lspconfig').clangd.setup {
  on_attach = function(_)
    bar.do_something()
  end,
}

Better

require('lspconfig').clangd.setup {
  on_attach = function(_)
    -- Will fail only if foo is never initialized
    require('foo').bar.do_something()
  end,
}

Now, imagine a scenario where nvim-lspconfig isn’t even present or loaded (e.g. when using a single configuration on multiple devices with different sets of plugins). Neovim’s startup would choke on require('lspconfig'), halting further configurations even if the plugin isn’t immediately required.

However, if nvim-lspconfig leveraged filetype.lua and vim.g, things would look different:

• Configuration snippet:

vim.g.lspconfig = {
  clangd = {
    filetypes = {'c', 'cpp'},
    -- additional settings...
  }
}

• The initialization script (orchestrated by the plugin, not the user):

-- ftplugin/c.lua
local clangd = vim.g.lspconfig and vim.g.lspconfig.clangd
if clangd.filetypes and vim.tbl_contains(clangd.filetypes, 'c') then
  -- config validations and clangd initialization performed and cached in 'lspconfig.cache.clangd'
  require('lspconfig.cache.clangd')
  require('lspconfig.configs').clangd.launch()
end

In such a setup, Neovim doesn’t break a sweat, even if nvim-lspconfig remains unloaded when init.lua processes vim.g.lspconfig.clangd.

Automatic dependency management’s Achilles’ Heel

Efforts to resolve pain points in Neovim’s plugin ecosystem have gravitated towards automatic dependency management.

Two notable initiatives³ are:

• Hosting plugins on LuaRocks.org and installing them with luarocks.
• The pkg.json (packspec) format specification for plugin metadata and dependencies.

Given Vim’s architecture (and by extension Neovim’s), there’s a specific initialization order where user preferences load before plugins. Ring a bell?

A lurking issue arises when plugins blend their configuration and initialization phases in one setup function. By doing this and handing over the initialization reins to the user, the core advantages of automatic dependency management risk getting undermined.

It should be a plugin’s duty to articulate its dependencies rather than leaving it to users or plugin managers. In the same spirit, plugins should defer their own initialization until all their dependencies are up and running.

Take a look at this snippet from neodev.nvim’s⁴ README:

-- IMPORTANT: make sure to setup neodev BEFORE lspconfig
require("neodev").setup({
  -- add any options here, or leave empty to use the default settings
})

-- then setup your lsp server as usual
local lspconfig = require('lspconfig')

-- example to setup lua_ls and enable call snippets
lspconfig.lua_ls.setup({
  settings = {
    Lua = {
      completion = {
        callSnippet = "Replace"
      }
    }
  }
})

Highlighting this, had there been a distinct line between configuration and initialization responsibilities, warnings like these wouldn’t be necessary.

Safeguarding initialization in dynamic environments

If you’re like me, and rely heavily on static type checking to fortify your code base, you’ll appreciate the confidence in not worrying about whether parts of your plugin are properly initialized.

Recall how I hinted at the beginning of this post that nil is evil? Consider this example from a plugin I use, which features a telescope.nvim extension. From a configuration standpoint, the typical way to add a Telescope extension looks something like this:

require('telescope').load_extension('yank_history')

Now, this is what happens if a user tries to invoke :Telescope yank_history before calling require('yanky').setup():

If setup has side-effects, it puts plugin authors in a tricky spot: They cannot confidently delegate control to users and simultaneously ensure that every component initializes when needed.

This issue illustrates a broader challenge: without type safety or strict initialization processes, we run into unpredictable behaviors. While dynamic languages like Lua offer flexibility, they also introduce the potential for such oversights, especially when initialization processes are handed over to the end-users.

What about namespace clashes and clutter?

The traditional way in Vimscript was to have a vim.g.<some_option> for each configuration option, typically prefixed with the plugin name, to avoid namespace clashes. This can introduce a lot of clutter. Fortunately, in Lua, vim.g.foo_bar can also be a single table (or a function that returns a table), which is no more likely to clash than a module name.

-- Instead of:
vim.g.plugin_name_option1 = "value1"
vim.g.plugin_name_option2 = "value2"
vim.g.plugin_name_option3 = "value3"

-- We can have:
vim.g.plugin_name = {
  option1 = "value1",
  option2 = "value2",
  option3 = "value3"
}

This approach keeps the global namespace clean and reduces the chances of clashes.

What about a configure function?

While there’s no inherent issue with a configure function (or even a setup function solely dedicated to configuration), its use can indeed simplify the validation of user configurations.

So, why do I caution against its adoption?

Remember the evolution of @norcalli’s export/setup pattern into a unified function? The crux of the matter lies in the fact that Lua functions can be inherently impure. This means there’s nothing stopping plugin developers from crafting their configure functions in less than ideal ways, such as:

M.configure(opts) = function
  -- <do something with opts>
  vim.api.nvim_launch_nuclear_warhead()
end

On the other hand, employing a vim.g variable offers an implicit assurance of its singular role in configuration. While this might introduce complexity in validating configurations, Neovim offers a robust solution: the :checkhealth mechanism. For an illustration of its effective utilization, see this example from my haskell-tools.nvim plugin.

But… Global variables are an antipattern?

Yes and no. Using global mutable state is frowned upon as an antipattern. However, we are discussing global configuration tables which we only read from. It’s common knowledge among developers, even those with little experience, that mutating global variables is a bad idea. Yet, it’s surprising how many seasoned developers overlook the importance of isolating side-effects.

Enter a world without setup

In light of these considerations, it is increasingly clear that the Neovim community may benefit from moving beyond the setup function, or at least the way it’s been traditionally employed. The setup function, as it stands today, isn’t the villain. However, the consequences of its misuse, ambiguity, and lack of clear separation of concerns in many plugins are real issues that need addressing.

So, what should the ideal look like?

1. Decoupled Configuration and Initialization: This has been reiterated multiple times, but it’s worth emphasizing. Configuration should be separated from initialization. This ensures that configuration is pure, readable, and unlikely to produce unexpected side effects.

2. Utilize vim.g for Configuration: As has been demonstrated, vim.g provides an ideal means to store plugin configuration. It aligns well with Vim conventions, provides an implicit assurance of its configuration-only role, and circumvents the need to require the plugin at startup.

3. Smart Initialization: Instead of relying on users or external mechanisms for activation, tools should employ intelligent self-initialization. For example, leveraging constructs like filetype.lua can defer their loading until genuinely required. However, for plugins with minimal startup footprints, lazy loading might be excessive. For plugins like telescope.nvim and nvim-cmp that support extensions, it would be nifty if Neovim provided a specification akin to :h runtimepath, so that extensions could register themselves automatically. Something along the lines of extension/<plugin>/register.lua⁵, which plugins could source at runtime.

4. Explicit Dependency Declaration: Plugins should clearly specify any dependencies, and the initialization of such plugins should ensure that these dependencies are loaded before proceeding.

Some caveats

No approach is without its drawbacks. Some possible criticisms of moving away from setup are:

• Learning Curve: This change would introduce a learning curve, especially for newer users who are already accustomed to the setup pattern. On the other hand, this approach discourages cargo cult programming and promotes genuine understanding.

• Migration: Existing plugins that heavily rely on the setup pattern might need significant rewrites. While this is an investment in future robustness, it might be daunting for some plugin authors and users alike.

• Performance: While unlikely, there’s always the potential for performance implications when making a sweeping change. However, any such implications would likely be minimal and far outweighed by the benefits.

• vim.g is a Vimscript/Lua bridge: As such, it may not be suitable for all use cases. For example, metatables are erased⁶. Although I consider metatables excessive for plugin configuration, a dedicated Lua API might be needed to address such concerns.

[Update] Change isn’t chaos

Addressing reservations some readers have about embracing change; to draw an analogy:

Just as transitioning away from fossil fuels doesn’t plunge us into perpetual darkness, or shifting to a more sustainable diet doesn’t lead to a world overrun by unchecked animal populations, the Neovim community won’t descend into chaos if we reconsider the use of setup. Change can be daunting, but it’s also a path to improvement.

[Update] Some additional points by @HiPhish

• setup locks users into Lua. Some people prefer Vimscript for configuration.
• Many setup functions do too much. There’s no need for inconsistent custom DSLs when Neovim already provides better mechanisms (like <Plug> for keymaps).
• A Lua function for configuration forces it all into one place. Maybe I want separate files for all my mappings and for all my custom highlight groups.

Guided migration: A step-by-step plan

For plugin maintainers, especially those with a large user base, the thought of introducing breaking changes can be daunting. However, with a structured approach, you can ensure a smooth transition for both you and your users. Here’s a suggested plan to phase out the setup function:

1. Embrace a Rigorous Release Cycle: Start by tagging releases with semantic versions and/or maintaining a stable branch if you haven’t already. This provides a clear framework for introducing changes.

2. Prioritize Separation of Concerns: If your plugin conflates configuration and initialization in a single function, consider splitting these concerns. Initially, transition to a setup function dedicated only to configuration while optimizing initialization. This change is unlikely to disrupt most users.

3. Support Both APIs Temporarily: By concurrently supporting both the old and new APIs, you provide users with a transition period. Consider implementing prompts (with an option to disable them) to guide users towards the new method.

4. Introduce the New API in a Separate Branch: Create a branch that omits the setup function, and actively promote this to your users. Encourage them to switch and provide feedback.

In Conclusion

In the constantly evolving world of Neovim plugins, it’s important to reflect on established patterns and consider their effectiveness. The setup pattern, while helpful in certain contexts, has shown potential pitfalls.

By championing a clear division between configuration and initialization and embracing tools like vim.g for the former, we pave the way for a more robust, predictable, and user-friendly Neovim plugin ecosystem.

As developers and users of Neovim plugins, it’s up to us to guide this evolution in a direction that benefits the entire community. Let’s strive for clarity, simplicity, and robustness as we move forward!

Credits

Thanks to the neorocks surgeons for proof-reading and input:

• @teto
• @vhyrro
• @NTBBloodbath
• @vigoux
• @vsedov

Lua, in the realm of Neovim, is a curious companion. For personal configuration tweaks, it’s incredibly responsive, giving me immediate feedback. Moreover, when I’m uncertain about an idea’s potential, Lua offers a forgiving platform for prototyping without commitment.

Yet, as the maintainer of a few plugins, who otherwise works with Haskell professionally, I have mixed feelings. Its dynamic typing casts shadows of unpredictability, making Neovim plugins susceptible to unexpected bugs at the wrong time.

When it comes to Neovim plugin (and Lua) development, the right tools can be game-changers. I’m aware of typed languages that compile to Lua, but here’s a native approach. Here, I’ll delve into my experiences in leveraging lua-language-server and its support for type annotations, demonstrating how they can elevate the robustness and expressiveness of your Lua code.

As an example, we will be attempting to define an algebraic data type (ADT), and using lua-language-server for static type checking.

What are algebraic data types (ADT)s?

For those steeped in the world of functional languages like Haskell, F#, or OCaml, the term ADT might sound familiar. If that’s you, feel free to skip ahead.

But if ADTs sound Greek to you, a straightforward analogy would be Rust Enums, which are, in fact, ADTs. They’re powerful constructs allowing versatile and type-safe data modeling.

I want to keep this post short, so I will assume this is enough information for you to know all the niceties that come with ADTs.

For a deeper dive, there’s a vast sea of resources available for you to explore.

Lua type annotations - the basics

As mentioned previously, lua-language-server is capable of producing diagnostics based on type annotations.

Here’s a basic example of defining a data type with a table:

---@class Foo
---@field bar string

---@type Foo
x = {
  bar = "hello",
}

And now the magic: Witness how lua-language-server utilizes these annotations to pinpoint type errors within Neovim:

Dynamic type annotations

In Lua, we’re not restricted to a single type. With annotations and runtime checks, we can express flexibility in our type expectations. For instance, consider a function that can accept either an instance of Foo or a string:

---@param foo Foo|string
local function print_foo(foo)
  if type(foo) == 'string' then
    print(foo)
  else
    print(foo.bar)
  end
end

Towards ADTs

Type annotations also permit the creation of aliases, streamlining the way we reference combined types. For instance:

---@alias FooOrString Foo|string

---@param foo FooOrString
local function print_foo(foo)

For those accustomed to Haskell, this syntax might ring a bell. Diving a bit deeper, let’s consider a more intricate use-case that I’ve employed in my neotest-haskell plugin. Here, I’ve depicted a type that might refer to an unopened file or, alternatively, its contents:

---Reference to a file
---@class FileRef
---@field file string

---Reference to a file's content
---@class FileContentRef
---@field content string

---@alias TestFile FileRef | FileContentRef

---Read a FileRef.
---@param file_ref FileRef
---@return FileContentRef content_ref
local function to_file_content_ref(file_ref)
  return {
    content = lib.files.read(file_ref.file),
  }
end

---@param query string|table The tree-sitter query.
---@param ref TestFile The test file.
---@return ...
function treesitter.iter_ts_matches(query, ref)
  local source
  if ref.file then
    ---@cast ref FileRef
    source = to_file_content_ref(ref)
  else
    ---@cast ref FileContentRef
    source = ref
  end
  -- <omitted for brevity> ...
end

With these annotations, we inch Lua ever closer to the potent expressiveness of ADTs. This achieves a harmonious blend of type versatility and precision.

Yet, it’s essential to acknowledge certain distinctions compared to real ADTs:

• FileRef and FileContentRef are independent type definitions, rather than data constructors.
• TestFile is an alias, not a concrete type.
• Lua doesn’t natively facilitate pattern matching.

This boils down to the fact that Haskell and Rust’s type systems are nominal, while Lua’s is structural¹.

Nevertheless, it’s feasible to simulate basic pattern matching with a function like this one:

---@generic T
---@param ref TestFile
---@param onFileRef fun(ref:FileRef):T
---@param onContentRef fun(ref:FileContentRef):T
---@return T
local function matchTestFile(ref, onFileRef, onContentRef)
  return ref.content
    ---@cast ref FileContentRef
    and onContentRef(ref)
    ---@cast ref FileRef
    or onFileRef(ref)
end

There’s an important caveat to note: While both the type annotation capabilities of lua-language-server and Neovim’s type annotations are continually evolving and improving, they’re not flawless. As of writing this post, the following misalignment can still occur:

---@type FileRef
x = {
  file = "/path/to/file",
  content = 5, -- Type-checks and breaks `matchTestFile` at runtime
}

There is a feature request, with an active discussion, so I’m optimistic about a resolution in the near future.

[Update]: Support for ---@class (exact) annotations has been added.

I’d also love to see the ability to report diagnostics if variables or functions are not annotated.

In the meantime, it pays to tread with caution.

Statically type checking your plugins

Diagnostics in your editor are great, but they’re not much of a defense if contributors or yourself can open PRs that disregard your type constraints. The silver lining? lua-language-server comes with a command-line interface.

> lua-language-server --checklevel=Warning --logpath=/tmp --configpath=.luarc.json --check ./lua
Diagnosis complete, 1 problems found, see /tmp/check.json

Here’s what’s happening:

• The --configpath option points to a configuration file, which can specify paths to dependencies, such as plugins and Neovim’s runtime path, among other things.
• --check specifies a file or a project directory.
• If there are any diagnostics (according to the --checklevel), lua-language-server will log a diagnostics report, check.json, inside the directory provided to --logpath.

To make this actionable in your workflow, I’ve crafted two utilities that integrate with GitHub Actions for static type-checking:

For Nix enthusiasts

For those in the Nix ecosystem, I’ve introduced a lua-ls hook to the pre-commit-hooks-nix framework. This serves dual purposes: as a git pre-commit hook and for Nix checks. I personally prefer this for my projects, though some optimization on the lua-ls pre-commit hook is on my to-do list. If you’re developing Neovim plugins, consider my template repository.

Why I prefer this approach: Any GitHub Actions can easily be reproduced locally, assuming you’ve set up Nix and have flakes enabled.

For the broader audience

For those not on the Nix train, I’ve got you covered with a simple GitHub action, named lua-typecheck-action. The setup is straightforward (albeit more limited), driven by a GitHub workflow YAML (eww).

I must mention that my focus has shifted away from this action, so major updates might be sparse. While there’s no direct support for dependencies, a workaround exists.

P.S. A plugin that I recommend adding as a dependency for lua-ls type-checking (as well as in your editor) is neodev.nvim. It is regularly updated with Neovim API type annotations for Neovim stable and nightly.

Wrapping up

Embracing tools like lua-language-server can significantly enhance our experience with Lua, while still allowing for rapid prototyping and ease of configuration. Although Lua might not naturally possess the rich type systems of languages like Haskell and Rust, with the right techniques, we can attempt to approximate their rigor and reliability. Here’s to safer, more expressive Lua coding in the future!

Dive Deeper

Inspired by this exploration into ADTs in Lua? I’d love to see how you apply these concepts:

• Try it out: Use these techniques in your own Neovim plugins.
• Share: Found a new approach or insight? Spread the word.
• Connect: Have feedback or questions? Feel free to open an issue on GitHub.

Credits

• Thanks to Owen for input and proof-reading.

In my previous post, I wrote about some pain points in the Neovim plugin ecosystem, and introduced the luarocks-tag-release GitHub action, which allows you to publish your Neovim plugins to LuaRocks, as a call to address those pain points.

At the end, I stated that I was planning to play around with a few ideas:

• Perhaps a package manager as a proof-of-concept?
• Maybe a package that can use Neovim as an interpreter to run LuaRocks so that it can use Neovim’s Lua API in test runs?

…and I ended up going down the second rabbit hole.

Why not just use plenary.nvim to test plugins?

Before Neovim 0.9, the status quo for Lua plugins has been to use plenary.nvim for testing. This still seems to be the case for many (including my own plugins, as of writing this post). Popular plugin templates still use plenary-test in their CI.

For example:

• ellisonleao/nvim-plugin-template
• m00qek/plugin-template.nvim
• nvim-lua/nvim-lua-plugin-template (Now uses busted)

What are the downsides of using plenary-test?

For one thing, it is a stripped-down re-implementation of busted. As such, it only supports a small subset of busted items. Functions like setup, teardown, insulate, expose, finally, or features like tagging tests, are not implemented.

Another downside is that different plugins have different approaches at managing the plenary-test dependency. An approach I see quite often is to clone the plenary.nvim repository into $HOME/.local/share/nvim/site/pack/vendor/start and then to symlink it to the project’s root or parent directory. This is not very intuitive for potential contributors. Plus, the fact that many plugins use git clone to fetch the HEAD of plenary.nvim’s master branch, is not ideal for reproducibility.

Enter Neovim 0.9

With the introduction of Neovim 0.9, you can now leverage the -l option to run lua scripts via the command-line interface. Combining this with -c lua [...], Neovim transforms into a full-fledged LuaJIT interpreter, providing access to the Neovim lua API.

To test this out, you can create a sayHello.lua file with the following content:

vim.print { "Hello", name }

Then run

nvim -c 'lua name = "teto"' -l sayHello.lua
> { "Hello", "teto" }

As it turns out, it’s quite easy to run busted tests using Neovim 0.9+ as the interpreter.

How to test your plugin with busted

Prerequisites

• If your plugin has any dependencies, it is a lot easier to set up if they are available on LuaRocks.
• So in case they aren’t, open an issue asking to publish releases to LuaRocks, e.g. using the luarocks-tag-release GitHub action.
• Install luarocks using your distro’s package manager and also install LuaJIT or Lua 5.1. The version doesn’t matter, since we’ll be using Neovim as the interpreter. But luarocks needs a real Lua installation that exposes its C header files to install certain dependencies.

Preparing your plugin

1. Add a .rockspec file

Add a rockspec named <my-plugin>-scm-1.rockspec¹ to your project’s root.

A minimal rockspec for testing might look something like this:

rockspec_format = '3.0'
package = '<my-plugin>'
version = 'scm-1'

test_dependencies = {
  'lua >= 5.1',
  'nlua',
  'nui.nvim',
}

source = {
  url = 'git://github.com/mrcjkb/' .. package,
}

build = {
  type = 'builtin',
}

This file tells luarocks and busted how to build your plugin as a Lua package and which dependencies to install before running tests.

2. Add a .busted file

Next, add a .busted file to the root of your project, to configure busted. This file should contain the following content:

return {
  _all = {
    coverage = false,
    lpath = "lua/?.lua;lua/?/init.lua",
    lua = "nlua",
  },
  default = {
    verbose = true,
  },
  tests = {
    verbose = true,
  },
}

Note

• The lpath is necessary to tell busted to look for your plugin’s source code in the lua directory.
• lua = "nlua" runs your tests with nlua (a Neovim-Lua CLI adapter) as the Lua interpreter.

3. Run your tests

That’s it! You can run your tests with

luarocks test --local
# or
busted

Without any arguments, busted looks for *_spec.lua files in a directory named spec.

Or if you want to run a single test file:

luarocks test spec/path_to_file.lua --local
# or
busted spec/path_to_file.lua

Using GitHub Actions to run tests

So far, this post has discussed using busted locally for testing Neovim plugins. However, to ensure thorough testing, compatibility, and bug detection across different environments, it’s essential to make this approach compatible with CI workflows like GitHub Actions.

For that, you can use the nvim-busted-action, which will take care of all the setup for you.

Moving forward

If this has motivated you to try out using luarocks and busted to test your Neovim plugins, I’d love to hear your feedback!

• Have you run into any issues?
• Is there still something Neovim-specific that plenary-test provides, which you are missing from this approach?
• Do you have any other thoughts?

Personally, I would like to see LuaRocks being able to run using Neovim, without having to install Lua. This possibility doesn’t seem far-fetched, especially considering that there are other communities that would also benefit from such an integration.

Note

This post has been updated to use nlua, instead of creating a busted wrapper script manually.

This is a follow-up on a series of blog posts by @teto that propose a solution to a major pain point of the Neovim plugin ecosystem - Dependency management.

As someone who only recently started maintaining Neovim plugins, I have been quite frustrated with my experience so far…

The current status quo

1. A horrible UX

…where users, not plugin authors, have to declare dependencies.

Here’s an example using packer.nvim:

use {
  'junnplus/lsp-setup.nvim',
  requires = {
    'neovim/nvim-lspconfig',
    'williamboman/mason.nvim',
    'williamboman/mason-lspconfig.nvim',
  }
}

This shouldn’t be the user’s responsibility.

What if dependencies are added or changed? It’s the user who has to update their config or deal with breakage.

2. Plugin authors copy/pasting code instead of using libraries

…because they don’t want their users to have to deal with this horrible UX.

I’ve been guilty of doing so myself.

3. Instability

As far as I know, we currently have no easy way to declare version constraints for dependencies. Something that LuaRocks supports, and which definitely should not be left up to the user.

All of this potentially gets worse with transitive dependencies.

The vicious cycle

As I see it, we have ourselves a dilemma:

• Neovim plugin authors don’t use LuaRocks because plugin managers don’t support it.
• Plugin managers don’t support LuaRocks properly because there aren’t enough plugins that use it.

This is something I’ve observed in many fields. For example, critics of electromobility have claimed that EVs will never be feasible, because we don’t have enough charging infrastructure. But which came first? Cars, or petrol stations?

I’m a strong believer that we need plugin authors to publish their packages to LuaRocks before package managers start supporting it. Just like we had cars before petrol stations, and electric vehicles before charging infrastructure.

Introducing the LuaRocks tag release action

As a catalyst to alleviate these issues, @teto and I have started the nvim-neorocks organisation and released the luarocks-tag-release GitHub action.

The goal is to minimise the effort for developers to release their plugins to LuaRocks, and to keep their published packages up to date.

How to get started as a plugin developer?

• All you need is a LuaRocks account and an API key.
• Add the API key to your repo’s GitHub actions secrets.
• Finally, create a .github/workflows/release.yml in your repository that uses the luarocks-tag-release action:

name: LuaRocks release
on:
  push:
    tags:
      - "*"

jobs:
  luarocks-release:
    runs-on: ubuntu-latest
    name: LuaRocks upload
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: LuaRocks Upload
        uses: nvim-neorocks/luarocks-tag-release@v4
        env:
          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
        with: # Optional inputs...
          dependencies: |
            plenary.nvim
            nvim-lspconfig

Whenever you push a tag (expected to adhere to semantic versioning), the workflow will:

1. Automatically fetch most of the relevant information (summary, license, …) from GitHub
2. Generate a rockspec for the release
3. Run a test to make sure LuaRocks can install your plugin locally
4. Publish your plugin to LuaRocks
5. Run a test to verify that your plugin can be installed from LuaRocks

If you need more flexibility, you can specify additional inputs or even use a rockspec template.

To advertise that your plugin is available on LuaRocks, you can add a shield to your README:

[![LuaRocks](https://img.shields.io/luarocks/v/<user>/<plugin>?logo=lua&color=purple)](https://luarocks.org/modules/<user>/<plugin>)

For example:

[![LuaRocks](https://img.shields.io/luarocks/v/neovim/nvim-lspconfig?logo=lua&color=purple)](https://luarocks.org/modules/neovim/nvim-lspconfig)

Here are some workflows and PRs you can use for inspiration:

• nvim-lspconfig
• haskell-tools.nvim
• telescope-manix - an extension that depends on telescope.nvim[^1].
• nvim-treesitter[^1] - A more complex example that uses a template to build with Make.
• plenary.nvim[^1] - Another example that uses a template so that LuaRocks runs tests.
• fzf-lua - A scheduled workflow that realeases versions based on the number of commits, if there have been new commits since the last run.

[^1] pull request

See also the workflow’s wiki page.

What can you do as a Neovim user?

If you don’t maintain your own plugins, but want to see the ecosystem improve, you can suggest the workflow to your favourite plugins, or open a pull request. In most cases, it’s extremely easy to add the workflow. See the above PR examples.

If you run in to problems or have any questions, don’t hesitate to open an issue or start a discussion!

What’s next?

For now, I am experimenting with a fork of LuaRocks, stripped down to the bare minimum needed to install packages. I am still uncertain of what that will lead to in the near future.

• Perhaps a package manager as a proof-of-concept?
• Maybe a package that can use Neovim as an interpreter to run LuaRocks so that it can use Neovim’s Lua API in test runs?

Hopeful for the future. Let’s make this happen!

Follow-up

Test your Neovim plugins with luarocks and busted