Nuxt 3 .output restore: missing integrity verification after deployment

Nuxt 3 and the Nitro engine do not provide a built-in checksum or manifest file to verify the integrity of the .output directory after it has been transferred to a production host. Because Nitro treats the filesystem as a source of truth at runtime, it does not perform a pre-flight validation of the bundle.

Runtime Behavior vs. Integrity

It is not advisable to rely on Nitro to surface deployment issues at runtime. The server's reaction to missing or corrupted files varies by location:

• Server Entry (.output/server/index.mjs): If this file is missing or corrupted, the Node.js process will fail to start immediately with a MODULE_NOT_FOUND or syntax error.
• Client Assets (.output/public/): If JS chunks or CSS files are missing, the server will start normally, but users will encounter 404 errors or silent failures when the browser attempts to load those assets.

Recommended Verification Strategy

To ensure the restored bundle is complete and unmodified, you must implement a custom manifest check within your CI/CD pipeline. The most reliable method is generating a SHA-256 hash list immediately after nuxi build and verifying it on the target host before starting the server.

Implementation Steps

1. Generate Manifest (Build Stage): After the build completes, create a manifest of all files in the .output directory.

   # Generate hashes for all files in .output
   find .output -type f -exec sha256sum {} + > .output/integrity.sha256

2. Transfer Bundle: Copy the entire .output folder (including the integrity.sha256 file) to the target host.
3. Verify Integrity (Deploy Stage): Before executing the start command, run a check against the manifest.

   # Verify files against the manifest
   sha256sum -c .output/integrity.sha256

4. Conditional Start: Only trigger the Nitro server start command if the sha256sum command returns an exit code of 0.

Verification Test

To confirm this workflow prevents silent failures, you can perform two tests in a staging environment:

• Delete a random file in .output/public and run the verification script; it should fail, preventing the deploy.
• Corrupt a line in .output/server/index.mjs and run the script; it should fail.

Diagnostic Detail Needed: Are you using a containerized deployment (e.g., Docker) or a direct filesystem transfer (e.g., rsync/scp)? If using Docker, integrity is typically guaranteed by the image layer hash, making a manual manifest redundant.