neovim: expose sideloadInitLua option to control the generation of init.lua

modules/misc/news/2026/04/2026-04-17_17-00-13.nix

@@ -0,0 +1,14 @@
+{ config, ... }:
+{
+  time = "2026-04-17T15:00:13+00:00";
+  condition = config.programs.neovim.enable;
+  message = ''
+    The module `programs.neovim` now writes to
+    {file}`$XDG_CONFIG_HOME/nvim/init.lua` by default.
+
+    If you want to manage {file}`$XDG_CONFIG_HOME/nvim/init.lua` yourself, you
+    can set {option}`programs.neovim.sideloadInitLua` to `true` to load the
+    content of {option}`programs.neovim.initLua` through neovim wrapper
+    arguments instead.
+  '';
+}

modules/programs/neovim.nix

@@ -260,6 +260,19 @@ in
         '';
       };
 
+      sideloadInitLua = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Enable to avoid writing the content of {var}`initLua` to the default
+          location {file}`$XDG_CONFIG_HOME/nvim/init.lua` and load it through
+          neovim wrapper arguments instead.
+
+
+          This is useful if you want to manage your own {file}`init.lua` imperatively.
+        '';
+      };
+
       initLua = mkOption {
         type = types.lines;
         default = "";
@@ -531,13 +544,6 @@ in
               opt = [ ];
             };
           };
-
-      # This is a hack to avoid breaking config for users that dont want an init.lua to get generated
-      # See https://github.com/nix-community/home-manager/pull/8734
-      # we basically check if the generated wrapper lua config has any user-set config
-      # if not HM avoids creating an init.lua
-      # this makes the logic harder to understand and maintain so hopefully we can find a way out
-      wrapperHasUserConfig = wrappedNeovim'.luaRcContent != wrappedNeovim'.providerLuaRc;
     in
     {
       warnings = legacyPluginTypeWarnings;
@@ -568,9 +574,9 @@ in
 
       programs.neovim.extraPackages = mkIf cfg.autowrapRuntimeDeps vimPackageInfo.runtimeDeps;
 
-      programs.neovim.extraWrapperArgs = mkIf (!wrapperHasUserConfig) [
+      programs.neovim.extraWrapperArgs = mkIf (cfg.sideloadInitLua && cfg.initLua != "") [
         "--add-flags"
-        ''--cmd 'lua dofile("${pkgs.writeText "wrapper-init-lua" wrappedNeovim'.luaRcContent}")' ''
+        ''--cmd 'lua dofile("${pkgs.writeText "wrapper-init-lua" cfg.initLua}")' ''
       ];
 
       programs.neovim.initLua =
@@ -588,7 +594,7 @@ in
               null;
         in
         lib.mkMerge [
-          (lib.mkIf wrapperHasUserConfig (
+          (lib.mkIf (wrappedNeovim'.luaRcContent != "") (
             # we want it to appear rather early
             lib.mkOrder 200 wrappedNeovim'.luaRcContent
           ))
@@ -615,6 +621,7 @@ in
         ++ [
           {
             "nvim/init.lua" = mkIf (cfg.initLua != "") {
+              enable = !cfg.sideloadInitLua;
               text = cfg.initLua;
             };
 

tests/modules/programs/neovim/default.nix

@@ -4,8 +4,7 @@
   neovim-runtime = ./runtime.nix;
   neovim-wrapper-args = ./wrapper-args.nix;
 
-  # waiting for a nixpkgs patch
-  neovim-no-init-vim = ./no-init.nix;
+  neovim-no-init-lua = ./no-init-lua.nix;
   neovim-extra-lua-init = ./extra-lua-init.nix;
   neovim-extra-lua-default = ./extra-lua-default.nix;
   neovim-extra-lua-empty-plugin = ./extra-lua-empty-plugin.nix;

tests/modules/programs/neovim/extra-lua-default.nix

@@ -1,10 +1,18 @@
+{ lib, ... }:
 {
   imports = [ ./stubs.nix ];
 
   programs.neovim.enable = true;
 
   nmt.script = ''
     nvimFolder="home-files/.config/nvim"
-    assertPathNotExists "$nvimFolder/init.lua"
+    initLua="home-files/.config/nvim/init.lua"
+    initLuaNormalized="$(normalizeStorePaths "$initLua")"
+
+    assertFileContent "$initLuaNormalized" ${builtins.toFile "init.lua-expected" (
+      lib.trim ''
+        vim.g.loaded_node_provider=0;vim.g.loaded_perl_provider=0;vim.g.ruby_host_prog='/nix/store/00000000000000000000000000000000-neovim-ruby-env/bin/neovim-ruby-host';vim.g.python3_host_prog='/nix/store/00000000000000000000000000000000-nvim-host-python3/bin/nvim-python3'
+      ''
+    )}
   '';
 }

tests/modules/programs/neovim/extra-lua-empty-plugin.nix

@@ -1,4 +1,4 @@
-{ pkgs, ... }:
+{ pkgs, lib, ... }:
 {
   imports = [ ./stubs.nix ];
 
@@ -13,7 +13,14 @@
   };
 
   nmt.script = ''
+    nvimFolder="home-files/.config/nvim"
     initLua="home-files/.config/nvim/init.lua"
-    assertPathNotExists "$initLua"
+    initLuaNormalized="$(normalizeStorePaths "$initLua")"
+
+    assertFileContent "$initLuaNormalized" ${builtins.toFile "init.lua-expected" (
+      lib.trim ''
+        vim.g.loaded_node_provider=0;vim.g.loaded_perl_provider=0;vim.g.ruby_host_prog='/nix/store/00000000000000000000000000000000-neovim-ruby-env/bin/neovim-ruby-host';vim.g.python3_host_prog='/nix/store/00000000000000000000000000000000-nvim-host-python3/bin/nvim-python3'
+      ''
+    )}
   '';
 }

tests/modules/programs/neovim/extra-lua-init.nix

@@ -14,6 +14,7 @@
     initLuaNormalized="$(normalizeStorePaths "$initLua")"
 
     assertFileContent "$initLuaNormalized" ${builtins.toFile "init.lua-expected" ''
+      vim.g.loaded_node_provider=0;vim.g.loaded_perl_provider=0;vim.g.ruby_host_prog='/nix/store/00000000000000000000000000000000-neovim-ruby-env/bin/neovim-ruby-host';vim.g.python3_host_prog='/nix/store/00000000000000000000000000000000-nvim-host-python3/bin/nvim-python3'
       -- initLua
     ''}
   '';

tests/modules/programs/neovim/no-init.nix → tests/modules/programs/neovim/no-init-lua.nix

@@ -10,6 +10,8 @@
     withPython3 = true;
     withRuby = false;
 
+    sideloadInitLua = true;
+
     extraPython3Packages = (
       ps: with ps; [
         jedi
@@ -22,6 +24,10 @@
       vim-fugitive
       { plugin = vim-sensible; }
     ];
+
+    initLua = ''
+      -- initLua
+    '';
   };
   nmt.script = ''
     nvimFolder="home-files/.config/nvim"

tests/modules/programs/neovim/wrapper-args.nix

@@ -41,6 +41,8 @@ in
     nvimBin="home-path/bin/nvim"
     export PATH="$TESTED/home-path/bin:$PATH"
     export HOME="$TMPDIR/hm-user"
+    # Load init.lua from $XDG_CONFIG_HOME/nvim/init.lua
+    export XDG_CONFIG_HOME="$TESTED/home-files/.config"
 
     assertBinaryContains() {
         local file="$TESTED/$1"
@@ -55,7 +57,8 @@ in
     assertNeovimExpr() {
         local var_name="$1"
         local expected_pattern="$2"
-        local output=$(nvim -i NONE --headless --cmd "echo $var_name" +q! 2>&1)
+        # Use -c to evaluate the expression after init.lua is loaded
+        local output=$(nvim -i NONE --headless -c "echo $var_name" +q! 2>&1)
         local exit_code=$?
 
         if [ $exit_code -ne 0 ]; then