docs/platforms: add standalone-legacy page

Documents the now-deprecated legacy standalone functions for existing users. Co-authored-by: Austin Horstman <khaneliman12@gmail.com>
2026-08-24 10:14:03 -05:00 · 2026-06-07 12:49:05 +00:00
parent 5dff6a8cab
commit a509dd2645
3 changed files with 144 additions and 0 deletions
@@ -16,6 +16,7 @@
 - [Nixvim Platforms](./platforms/index.md)
@PLATFORM_OPTIONS@
 	- [Standalone](./platforms/standalone.md)
+	- [Standalone (legacy)](./platforms/standalone-legacy.md)

 # Options

@@ -0,0 +1,140 @@
+# Legacy Standalone Functions
+
+> [!WARNING]
+> The functions documented on this page are deprecated.
+> New configurations should prefer `nixvim.lib.evalNixvim`.
+>
+> See [Standalone Usage](./standalone.md) for the recommended approach.
+
+## makeNixvim
+
+`makeNixvim` is available at:
+
+```nix
+nixvim.legacyPackages.${system}.makeNixvim
+```
+
+It accepts a single Nixvim module and returns a Nixvim package.
+
+```nix
+nixvim.legacyPackages.${system}.makeNixvim {
+  colorschemes.gruvbox.enable = true;
+}
+```
+
+This is equivalent to evaluating a configuration and using its package output.
+
+> [!TIP]
+> `makeNixvim module` is equivalent to `makeNixvimWithModule { inherit module; }`.
+
+## makeNixvimWithModule
+
+`makeNixvimWithModule` is available at:
+
+```nix
+nixvim.legacyPackages.${system}.makeNixvimWithModule
+```
+
+It accepts an attribute set with the following fields:
+- `module`
+- `pkgs`
+- `extraSpecialArgs`
+
+The only required field is `module`.
+
+```nix
+nixvim.legacyPackages.${system}.makeNixvimWithModule {
+  module = ./config;
+}
+```
+
+## Test derivation helpers
+
+### check.mkTestDerivationFromNvim
+
+Available at:
+
+```nix
+nixvim.lib.${system}.check.mkTestDerivationFromNvim
+```
+
+Accepts:
+
+```nix
+{
+  name = "example";
+  nvim = myNvim;
+}
+```
+
+where `nvim` is a Nixvim package.
+
+### check.mkTestDerivationFromNixvimModule
+
+Available at:
+
+```nix
+nixvim.lib.${system}.check.mkTestDerivationFromNixvimModule
+```
+
+Accepts the same arguments as `makeNixvimWithModule` and produces a test derivation.
+
+## Extending an existing package
+
+Packages produced by the legacy APIs expose an `extend` function.
+
+```nix
+{ makeNixvim }:
+
+let
+  first = makeNixvim {
+    extraConfigLua = "-- first stage";
+  };
+
+  second = first.extend {
+    extraConfigLua = "-- second stage";
+  };
+
+  third = second.extend {
+    extraConfigLua = "-- third stage";
+  };
+in
+third
+```
+
+This produces:
+
+```lua
+-- first stage
+-- second stage
+-- third stage
+```
+
+The modern equivalent is `configuration.extendModules`.
+
+## Accessing configuration values
+
+Legacy packages expose the evaluated configuration through the `config` attribute.
+
+```nix
+nvim.config
+```
+
+## Accessing options
+
+Legacy packages expose module options through the `options` attribute.
+
+```nix
+nvim.options
+```
+
+## Migration
+
+| Legacy API                                                    | Modern equivalent                                              |
+| ------------------------------------------------------------- | -------------------------------------------------------------- |
+| `makeNixvim module`                                           | `(evalNixvim { modules = [ module ]; }).config.build.package`  |
+| `makeNixvimWithModule args`                                   | `(evalNixvim { ... }).config.build.package`                    |
+| `check.mkTestDerivationFromNixvimModule args`                 | `(evalNixvim { ... }).config.build.test`                       |
+| `check.mkTestDerivationFromNvim { name = ""; inherit nvim; }` | `nvim.config.build.test`                                       |
+| `package.extend module`                                       | `((evalNixvim { ... }).extendModules { modules = [ module ]; }).config.build.package` |
+
@@ -119,3 +119,6 @@ The resulting configuration exposes several useful outputs:
 For a complete example, see our [standalone flake template](https://github.com/nix-community/nixvim/tree/main/templates/simple).

 For more information, including extending configurations and accessing configuration values, see [Standalone Usage](../platforms/standalone.md).
+
+> [!IMPORTANT]
+> If you are using the legacy standalone APIs (`makeNixvim`, `makeNixvimWithModule`, etc.), see [Legacy Standalone Functions](../platforms/standalone-legacy.md).