LDX is a small utility for resolving Lua dependencies through Nix to provide a better developer experience.
It also has a Neovim plugin to manage workspace features, but that was purged and re-added. It has not yet been tested again.
The core feature of LDX is resolving Lua dependencies, such as LuaRocks packages
through the Nix package manager, and updating the .luarc.json accordingly, so
you can enjoy better type support.
LDX works by creating a .ldx.json file at the root of your project and then
running the ldx command. LDX fetches the dependencies, adds them to GC roots
and updates the .luarc.json with the resolved packages. The generated paths
are resolved through environment variables to avoid cross-machine path resolution
issues.
Currently, LDX works in two phases: first, it syncs the dependencies (by resolving
them and updating .luarc.json); then it sources the generated environment.
See Example.
Future versions will support evaluating the environment directly after syncing.
Note
LDX only updates the workspace.library field, and leaves the rest of .luarc.json
untouched.
LDX only supports dependencies that are packaged for Nix. They can be anywhere, though, such as from the current flake, nixpkgs, or from the relative flakes. It cannot fetch them from LuaRocks or other registries directly and there are no plans. to add such features.
Add ldx to your flake and add ldx to your dev shell.
{
inputs = {
# rest of your inputs
ldx = {
url = "github:ar-at-localhost/ar-at-localhost";
nixpkgs.follow = "nixpkgs";
};
};
# ...
outputs = {
#...
# assuming system, pkgs, default variable
devShells."$system".default = {
packages = [
#...
ldx.packages.$system.default
];
shellHook = ''
# Sync first
ldx sync
# Source the env
eval $(ldx env)
'';
};
};
}Tip
The flake also provides an overlay, overlays.default, which adds ldx, vimPlugins.ldx to pkgs.
{
#...
nixpkgs.overlays = [
inputs.ldx.overlays.default
#...
];
}Run ldx --help to see the available commands and usage instructions.
Let's say our workspace depends on Snacks.nvim, Orgmode.nvim, and is itself a Neovim plugin. It therefore needs Neovim runtime, Snacks.nvim and Orgmode types to provide an effective developer experience.
We'll create a .ldx.json and declare these dependencies.
[
"vim",
"nixpkgs:vimPlugins.snacks-nvim"
"nixpkgs:vimPlugins.orgmode"
]As you can see, the configuration is simply a JSON array listing the dependencies, in the supported format.
Once we run LDX, it resolves these dependencies, and our updated
.luarc.json may look like this:
# `.` refers to cwd as workspace root, assuming we're running from workspace root
# It is optional, though, and defaults to the current working directory.
# 1. Run ldx to fetch the dependencies and update the luarc
ldx sync .
# 2. Source the environment produced by the ldx to resolve environment variables
eval $(ldx env){
"workspace": {
"library": [
"${env:LDX_LOCAL____YALMS_LUA}",
"${env:LDX_VIMPLUGINS_ORGMODE}",
"${env:LDX_VIMPLUGINS_SNACKS_NVIM}",
"${env:LDX_VIM_RUNTIME}"
]
},
"diagnostics": {
"globals": []
},
"runtime": {
"version": "LuaJIT",
"path": [
"./lua/?.lua",
"./lua/?/init.lua"
]
}
}The configuration is a JSON array containing dependency names. These names can follow one of the following formats:
Some dependencies may have a keyword to add them. Currently,
vim is only such dependency. It resolves Neovim runtime libraries.
These dependencies use a nixpkgs: prefix to indicate that they should
be reoslved from nixpkgs of the current flake.
nixpkgs:vimPlugins.snacks-nvimNeovim Snacksnixpkgs:vimPlugins.orgmodeNeovim Orgmodenixpkgs:vimPlugins.plenary-nvimNeovim Plenary
Note
You need to provide full attribute path, if package is nested within package sets,
as in the vimPlugins examples above.
Packages from current flake or other relative flakes are added with relative
flake URI. For example, .#foo, ..#bar etc.
..#foo.#foo./bar/baz#foo
Relative Lua workspaces can be packaged directly.
.././foo./bar/baz/foo
If you're looking for a similar solution outside of Nix ecosystem, check out Lux.