# 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`][evalNixvim]. [NixOS]: ./nixos.md [Home Manager]: ./hm.md [nix-darwin]: ./darwin.md [evalNixvim]: ../lib/nixvim/modules/index.md#lib.nixvim.modules.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`. ```nix 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][evalModules-type]. - `extendModules`: Extends the current configuration with additional modules. See [upstream docs][extendModules]. For more information, see Nixpkgs' [`evalModules` output][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: ```nix { 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: ```nix { checks.${system}.default = configuration.config.build.test; } ``` ## Extending a configuration Configurations can be extended using `extendModules`. ```nix 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`][extendModules] documentation. ## Accessing configuration values Evaluated option values are available through `config`. For example: ```nix 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`: ```nix { 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`. ```nix { 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][lib.nixvim.modules] for more detail. ### buildNixvim Builds a Nixvim package from a module or list of modules. ```nix buildNixvim { imports = [ ./config ]; nixpkgs.hostPlatform = system; } ``` Equivalent to: ```nix (evalNixvim { inherit system; modules = [ ./config ]; }).config.build.package ``` ### buildNixvimWith Like `buildNixvim`, but accepts the full set of arguments supported by `evalNixvim`. ```nix buildNixvimWith { inherit system; modules = [ ./config ]; } ``` Equivalent to: ```nix (evalNixvim { inherit system; modules = [ ./config ]; }).config.build.package ``` ### testNixvim Produces a test derivation from an existing Nixvim package. ```nix testNixvim myNvim ``` Equivalent to: ```nix myNvim.config.build.test ``` ### testNixvimWith Evaluates a configuration and returns its test derivation. ```nix testNixvimWith { inherit system; modules = [ ./config ]; } ``` Equivalent to: ```nix (evalNixvim { inherit system; modules = [ ./config ]; }).config.build.test ``` [lib.nixvim.modules]: ../lib/nixvim/modules/index.md [evalModules-output]: https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules [evalModules-type]: https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules-return-value-type [extendModules]: https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules-return-value-extendModules