wrappers: support `extraSpecialArgs`

[rkuklik]

Hi.

I use nixvim both standalone and with home-manager. I have custom modules
written for standalone usage, but home-manager the options are namespaced under
programs.nixvim. Therefore, I import my modules like so:

{
  self, # flake reference
  ...
}:
{
  programs = {
    nixvim = {
      enable = true;
      imports = with self.nixvimModules; [
        module-name
      ];
    };
  };
}

However, module-name also takes self and other custom args, which fails with
infinite recursion.

I solve this by reimplementing the nixvim home-manager module to add my args as
extraSpecialArgs, which is suboptimal.

Is there a better solution than this? I think the best way to enable this would be
the approach home-manager takes under NixOS by having
home-manager.extraSpecialArgs option. I can submit a PR with this feature, if you
would be interested.

Thanks in advance.

[MattSturgeon]

This is one of the unfortunate side-effects of modules that depend on custom arguments: they become less reusable, because the arguments have to be in scope wherever the module is imported.

Are your arguments special?

_module.args is usually a better fit than specialArgs, because it is defined inside modules and participates in the module system.

That said, _module.args still shares some pitfalls with specialArgs. If a module expects an argument provided by a module that isn't imported, evaluation fails; multiple modules defining the same name can collide; etc.

Often, custom options are a cleaner, more idiomatic choice than arguments. Another approach is to define modules within a wider file so that the dependency is in scope lexically.

If you're importing modules from self, like in your example, then yes it needs to be "special"; i.e. defined outside of the module system eval.

importApply

Another approach is to wrap a module with lib.modules.importApply. This embeds the dependency directly into the imported module, avoiding global argument threading. It does require rethinking how you structure your modules.

• Noogle reference
• flake-parts explanation

This achieves a similar effect to lexical scoping while still allowing you to define modules in separate files.

Submodule limitations

programs.nixvim is a submodule, whose options come from Nixvim’s modules. All programs.nixvim.* values—including a potential programs.nixvim.extraSpecialArgs option—are evaluated inside that submodule. Special args must be defined before the submodule is evaluated—that's what makes them "special"—so they can’t be added as regular Nixvim options.

As an alternative, you could define nixvimExtraSpecialArgs outside the programs.nixvim namespace to bypass the fixpoint requirement. This works technically but leads to inconsistent option naming and a worse user experience.

You could also wrap programs.nixvim in a custom type to extract extraSpecialArgs before delegating to the submodule, but that isn’t worth the added complexity.

Refactoring platform wrapper modules

A cleaner long-term solution is to make the NixOS/Home Manager/nix-darwin “platform wrapper” modules outputs of a Nixvim configuration, using extendModules internally. For example:

(evalNixvim {
  extraSpecialArgs.foo = "bar";
}).config.build.homeManagerModule

This generates a Home Manager module that injects foo into the Nixvim evaluation. It also lets users produce a Home Manager module containing their full Nixvim configuration, without needing to re-import their Nixvim modules into Home Manager.

[rkuklik]

Oh, thank you, I didn't know about importApply, but it seems to be exactly what I need.
I originally did wrap my nixvim config into a special type (which isn't ideal).

Applying special args at the flake level solved my issue. Should I close the issue or do you
want to add specialArgs anyway?