Package Next.js App as Nix Derivation and deploy as Service on NixOS

ed store paths.

2. Prefetch Dependency Hash

Nix requires a hash of the package-lock.json to verify dependency integrity. This hash is generated using prefetch-npm-deps.

Command:

nix run nixpkgs#prefetch-npm-deps -- package-lock.json

Output: The command returns a hash string (e.g., sha256-abc123...). This value must be captured and inserted into the flake. If package-lock.json changes, this command must be re-run to update the hash.

3. Define the Application Flake

The application flake defines the build logic and the NixOS module. This flake can be consumed by any NixOS host.

File: flake.nix

{
  description = "Production-grade Next.js service package";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  };

  outputs = { self, nixpkgs }:
    let
      # Define supported architectures
      systems = [ "x86_64-linux" "aarch64-linux" ];
      forAllSystems = nixpkgs.lib.genAttrs systems;

      # Helper to construct the package
      mkAppPackage = pkgs: pkgs.buildNpmPackage {
        pname = "corporate-dashboard";
        version = "1.0.0";
        src = ./.;

        # CRITICAL: Update this hash when package-lock.json changes
        npmDepsHash = "sha256-PLACEHOLDER_REPLACE_ME";

        # Node version pinning ensures runtime consistency
        nodejs = pkgs.nodejs_24;

        # Post-build steps to copy static assets into the output
        # Next.js standalone output does not include public/ or static/ automatically
        postBuild = ''
          mkdir -p $out/public $out/.next/static
          cp -r public/* $out/public/
          cp -r .next/static/* $out/.next/static/
        '';

        # Install phase moves the standalone server to the store path
        installPhase = ''
          cp -r .next/standalone/* $out/
        '';
      };
    in
    {
      packages = forAllSystems (system: {
        default = mkAppPackage nixpkgs.legacyPackages.${system};
      });

      # NixOS Module definition for service management
      nixosModules.dashboard = { config, lib, pkgs, ... }:
        let
          cfg = config.services.corporate-dashboard;
          basePkg = self.packages.${pkgs.system}.default;

          # Allow environment variables to override build attributes
          runtimePkg = basePkg.overrideAttrs (old: {
            env = cfg.environment;
          });
        in
        {
          options.services.corporate-dashboard = {
            enable = lib.mkEnableOption "Corporate Dashboard Next.js Service";

            environment = lib.mkOption {
              type = lib.types.attrsOf lib.types.str;
              default = {};
              description = "Environment variables passed to the Node.js process.";
              example = {
                PORT = "3000";
                NODE_ENV = "production";
                DATABASE_URL = "postgresql://...";
              };
            };
          };

          config = lib.mkIf cfg.enable {
            systemd.services.corporate-dashboard = {
              description = "Next.js Corporate Dashboard";
              wantedBy = [ "multi-user.target" ];
              after = [ "network.target" ];

              environment = cfg.environment;

              serviceConfig = {
                ExecStart = "${pkgs.nodejs_24}/bin/node ${runtimePkg}/server.js";
                Restart = "always";
                RestartSec = "5s";
                # Security hardening
                NoNewPrivileges = true;
                ProtectSystem = "strict";
                ReadWritePaths = [ "/var/lib/dashboard" ];
              };
            };
          };
        };
    };
}

Architecture Decisions:

• buildNpmPackage: This function handles npm installation and caching efficiently. It uses the npmDepsHash to ensure the dependency tree is immutable.
• postBuild Asset Copying: The standalone output excludes the public directory and .next/static assets. The postBuild hook explicitly copies these into the output path ($out), ensuring the server can serve static files.
• overrideAttrs for Environment: The module uses overrideAttrs to inject environment variables. This allows the service definition to pass runtime configuration without modifying the derivation's build logic.
• Security Hardening: The systemd service includes NoNewPrivileges and ProtectSystem to minimize the attack surface, adhering to production security best practices.

4. Consume the Flake on NixOS

The host system imports the application flake and enables the service via its configuration.

File: host/flake.nix

{
  description = "NixOS Server Configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    dashboard-app.url = "github:org/corporate-dashboard";
  };

  outputs = { self, nixpkgs, dashboard-app }: {
    nixosConfigurations.server = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        dashboard-app.nixosModules.dashboard
      ];
    };
  };
}

File: host/configuration.nix

{ config, pkgs, ... }:
{
  # Import the dashboard module
  services.corporate-dashboard = {
    enable = true;

    environment = {
      PORT = "3000";
      NODE_ENV = "production";
      # Inject secrets via NixOS secrets management or environment files
      # DATABASE_URL = config.age.secrets.db-url.path; 
    };
  };

  # Network configuration
  networking.firewall.allowedTCPPorts = [ 3000 ];

  # System user for service isolation (optional but recommended)
  users.users.dashboard = {
    isSystemUser = true;
    group = "dashboard";
  };
  users.groups.dashboard = {};
}

Pitfall Guide

Pitfall	Explanation	Fix
Missing Standalone Config	If output: "standalone" is omitted, buildNpmPackage may succeed but produce an incorrect structure, or the installPhase will fail because .next/standalone does not exist.	Verify next.config.ts contains output: "standalone". Run npm run build locally to confirm the directory structure.
Hash Mismatch	Adding or updating a dependency changes package-lock.json. If the npmDepsHash in the flake is not updated, the build fails with a hash mismatch error.	Run nix run nixpkgs#prefetch-npm-deps -- package-lock.json after any dependency change and update the flake.
Static Asset Loss	The standalone output does not include the public folder or .next/static. The app may build successfully but return 404s for images or CSS.	Ensure postBuild explicitly copies public and .next/static into $out. Verify paths match your project structure.
Environment Variable Leakage	Nix derivations are built in a sandbox. Environment variables defined in the flake are not automatically available at runtime unless passed via the systemd service config.	Use the environment option in the NixOS module to pass variables. Avoid hardcoding secrets in the derivation.
Node Version Drift	The build may use a different Node version than the runtime, causing ABI incompatibilities with native modules.	Pin nodejs in buildNpmPackage and ensure the ExecStart uses the same version (e.g., pkgs.nodejs_24).
Permission Errors	The service may fail to start if the store path is not readable or if the service user lacks permissions.	Ensure the systemd service runs as a user with read access to /nix/store. Use ProtectSystem = "strict" carefully to allow read access to the store.
Flake Lock Staleness	The flake.lock file may become outdated, causing the build to use an old version of nixpkgs or dependencies.	Regularly run nix flake update to refresh inputs and commit the updated lock file.

Production Bundle

Action Checklist

• Verify Standalone Output: Ensure next.config.ts has output: "standalone" and npm run build generates .next/standalone.
• Prefetch Hash: Run prefetch-npm-deps and update npmDepsHash in flake.nix.
• Asset Copying: Confirm postBuild copies public and .next/static to $out.
• Module Definition: Define the NixOS module with enable and environment options.
• Host Integration: Import the app flake in the host flake.nix and enable the service in configuration.nix.
• Security Review: Apply systemd hardening options (NoNewPrivileges, ProtectSystem).
• Rebuild: Run nixos-rebuild switch and verify the service status with systemctl status corporate-dashboard.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High Security / Compliance	Nix Derivation	Immutable builds, auditability, and atomic rollbacks meet strict compliance requirements.	Low (No container registry costs)
Multi-Cloud / Kubernetes	Docker Container	Nix is less portable to non-NixOS environments; Docker is standard for K8s.	Medium (Registry storage)
Rapid Prototyping	PM2 / Direct Node	Simpler setup for local development; Nix adds overhead for throwaway projects.	Low
Long-Term Maintenance	Nix Derivation	Reproducibility reduces technical debt and deployment failures over time.	Low (Reduced debugging time)

Configuration Template

Application Flake (flake.nix):

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  outputs = { self, nixpkgs }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in
    {
      packages.${system}.default = pkgs.buildNpmPackage {
        pname = "my-nextjs-app";
        version = "0.0.1";
        src = ./.;
        npmDepsHash = "sha256-..."; # Update via prefetch-npm-deps
        nodejs = pkgs.nodejs_24;
        postBuild = ''
          mkdir -p $out/public $out/.next/static
          cp -r public/* $out/public/
          cp -r .next/static/* $out/.next/static/
        '';
        installPhase = ''
          cp -r .next/standalone/* $out/
        '';
      };

      nixosModules.app = { config, lib, pkgs, ... }:
        let cfg = config.services.my-nextjs-app;
        in {
          options.services.my-nextjs-app.enable = lib.mkEnableOption "My Next.js App";
          options.services.my-nextjs-app.environment = lib.mkOption {
            type = lib.types.attrsOf lib.types.str;
            default = {};
          };
          config = lib.mkIf cfg.enable {
            systemd.services.my-nextjs-app = {
              wantedBy = [ "multi-user.target" ];
              environment = cfg.environment;
              serviceConfig.ExecStart = "${pkgs.nodejs_24}/bin/node ${self.packages.${pkgs.system}.default}/server.js";
              serviceConfig.Restart = "always";
            };
          };
        };
    };
}

Host Configuration (configuration.nix snippet):

{
  services.my-nextjs-app = {
    enable = true;
    environment = {
      PORT = "3000";
      NODE_ENV = "production";
    };
  };
  networking.firewall.allowedTCPPorts = [ 3000 ];
}

Quick Start Guide

1. Configure Next.js: Add output: "standalone" to next.config.ts.
2. Generate Hash: Run nix run nixpkgs#prefetch-npm-deps -- package-lock.json and copy the hash.
3. Create Flake: Write flake.nix using the template above, inserting the hash.
4. Deploy: Import the flake into your NixOS host configuration, enable the service, and run nixos-rebuild switch.
5. Verify: Check systemctl status my-nextjs-app and access the application on the configured port.