Standalone Usage #
Standalone usage refers to using Nixvim directly as a package, rather than through the NixOS, Home Manager, or nix-darwin modules.
In this mode, Nixvim configurations are evaluated explicitly using evalNixvim.
Options #
When used standalone, Nixvim's options are available directly, without any prefix/namespace.
This is unlike the other modules which typically use a programs.nixvim.* prefix.
There are no standalone-specific options available.
Evaluating a configuration #
When used standalone, Nixvim configurations are evaluated using nixvim.lib.evalNixvim.
configuration = nixvim.lib.evalNixvim {
inherit system;
modules = [ ./config ];
};
The result is a Nix module-system configuration.
modules
↓
evalNixvim
↓
configuration
Notable attributes include:
config: The nested attribute set of all merged option values.options: The nested attribute set of all option declarations.type: A module system type. See upstream docs.extendModules: Extends the current configuration with additional modules. See upstream docs.
For more information, see Nixpkgs' evalModules output docs.
See the lib.nixvim.modules reference for complete API documentation.
Building a package #
Nixvim exposes build outputs through the evaluated configuration.
The wrapped Neovim package is available as configuration.config.build.package.
For example:
{
packages.${system}.default = configuration.config.build.package;
}
Building tests #
A test derivation is available as configuration.config.build.test.
It can be used to smoke-test your Nixvim configuration.
For example, as a flake check:
{
checks.${system}.default = configuration.config.build.test;
}
Extending a configuration #
Configurations can be extended using extendModules.
let
base = nixvim.lib.evalNixvim {
inherit system;
modules = [
{
extraConfigLua = "-- first stage";
}
];
};
extended = base.extendModules {
modules = [
{
extraConfigLua = "-- second stage";
}
];
};
in
extended.config.build.package
See the upstream lib.evalModules → extendModules documentation.
Accessing configuration values #
Evaluated option values are available through config.
For example:
configuration.config.colorschemes.gruvbox.enable
⇒ true
This can be useful when other parts of your NixOS, Home Manager, or nix-darwin configuration need access to values defined by Nixvim.
Accessing options #
Module options are available through options.
This can be useful when configuring nixd:
{
plugins.lsp.servers.nixd = {
enable = true;
settings.options.nixvim.expr =
''(builtins.getFlake "/path/to/flake").packages.${system}.default.options'';
};
}
Package outputs also expose config and options through passthru attributes.
Using in another configuration #
Here is an example of integrating a standalone configuration into a NixOS or Home Manager configuration.
The example assumes the standalone configuration is exported as the default package of a flake named nixvim-config.
{ inputs, system, ... }:
{
# NixOS
environment.systemPackages = [
inputs.nixvim-config.packages.${system}.default
];
# Home Manager
home.packages = [
inputs.nixvim-config.packages.${system}.default
];
}
Convenience functions #
For simple use cases, Nixvim provides helper functions that combine configuration evaluation and output selection.
These are thin wrappers around evalNixvim selecting config.build.package or config.build.test.
See the reference docs for more detail.
buildNixvim #
Builds a Nixvim package from a module or list of modules.
buildNixvim {
imports = [ ./config ];
nixpkgs.hostPlatform = system;
}
Equivalent to:
(evalNixvim {
inherit system;
modules = [ ./config ];
}).config.build.package
buildNixvimWith #
Like buildNixvim, but accepts the full set of arguments supported by evalNixvim.
buildNixvimWith {
inherit system;
modules = [ ./config ];
}
Equivalent to:
(evalNixvim {
inherit system;
modules = [ ./config ];
}).config.build.package
testNixvim #
Produces a test derivation from an existing Nixvim package.
testNixvim myNvim
Equivalent to:
myNvim.config.build.test
testNixvimWith #
Evaluates a configuration and returns its test derivation.
testNixvimWith {
inherit system;
modules = [ ./config ];
}
Equivalent to:
(evalNixvim {
inherit system;
modules = [ ./config ];
}).config.build.test