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