next-zombie

v1.9.0

Published

2 months ago

Fix ENOENT _buildManifest.js.tmp error. Auto-restart Next.js Turbopack dev server on crash. Supports Next.js 13.4+.

next-zombie 🧟

Fix "ENOENT _buildManifest.js.tmp" error automatically
Turbopack crash recovery | Auto-restart for Next.js 13.4+

Turbopack is fast. But it crashes. Cache corruption, _buildManifest.js.tmp errors, random ENOENT failures — sound familiar?

next-zombie watches your Next.js dev server and automatically restarts it when Turbopack crashes. No more manual restarts. No more rm -rf .next. Just keep coding.

Works with Next.js 13.4+ using Turbopack (especially useful in 15+ where Turbopack is default)

The Problem

Turbopack (Next.js 13.4+) is blazing fast, but unstable:

⨯ [Error: ENOENT: no such file or directory, open '.next/static/development/_buildManifest.js.tmp']

When does this happen?

Next.js 13.4-14.x with --turbo flag
Next.js 15+ (Turbopack is default)
Next.js 16+ (same Turbopack issues)

Your choices:

Disable Turbopack — Stable but slower (next dev --turbo=false)
Use next-zombie — Keep Turbopack speed + auto-recovery

Quick Start

npx next-zombie

That's it. Your dev server now auto-recovers from crashes.

Install

npm install -D next-zombie
# or
pnpm add -D next-zombie
# or
yarn add -D next-zombie

Add to package.json:

{
  "scripts": {
    "dev": "next-zombie"
  }
}

Features

| Feature | Description | |---------|-------------| | Auto-Recovery | Detects crashes and restarts in ~700ms | | Keyboard Shortcuts | Interactive controls: restart, clear cache, open browser | | Browser Auto-Refresh | Automatically refreshes browser after restart | | Auto Install | Fixes missing modules with automatic npm install | | Port Conflict Resolution | Automatically finds next available port | | Cache Cleanup | Clears .next before restart | | Smart PM Detection | Detects npm/pnpm/yarn/bun from lockfile | | Cross-Platform | Works on macOS, Linux, and Windows | | Session Report | Detailed stats with error breakdown on exit | | Zero Config | Works with your existing dev script |

How It Works

next-zombie
    │
    ├─► Clean .next cache
    │
    ├─► Start: pnpm run dev
    │
    ├─► Monitor stdout/stderr
    │       │
    │       ├─► Cache error detected?
    │       │       │
    │       │       └─► Kill process tree
    │       │           └─► Restart (after 500ms)
    │       │
    │       └─► Process crashed?
    │               │
    │               └─► Restart (after 200ms)
    │
    └─► Ctrl+C → Clean exit

Keyboard Shortcuts

next-zombie runs in interactive mode with keyboard controls:

┌─────────────────────────────────────────────────────┐
│  🧟 next-zombie v1.8.0                              │
│  Press: r=restart c=clear o=open h=help q=quit      │
└─────────────────────────────────────────────────────┘

| Key | Action | |-----|--------| | r | Restart dev server manually | | c | Clear .next cache (without restart) | | o | Open browser (localhost:PORT) | | h | Show keyboard shortcuts help | | q | Quit | | Enter | Add blank line (for log separation) |

Note: Keyboard shortcuts are disabled in non-TTY environments (CI, pipes).

Detected Errors

next-zombie auto-restarts on Turbopack internal errors only (not user code errors):

Cache temp file corruption:

_buildManifest.js.tmp ENOENT
build-manifest.json.tmp EPERM
_devMiddlewareManifest errors

Turbopack panics:

FATAL: An unexpected Turbopack error occurred
Rust panic messages (panicked at turbopack/...)

Cache directory errors:

.next/static/development/ ENOENT
.next/cache/ ENOENT
Windows EPERM on .tmp files

NOT restarted (user code errors):

SyntaxError, TypeError, ReferenceError
Module not found errors
API/runtime errors

Port Conflict Resolution

When port 3000 (or any port) is already in use, next-zombie automatically tries the next port:

Error: listen EADDRINUSE: address already in use :::3000

[next-zombie] Port 3000 in use
[next-zombie] Trying port 3001...
[next-zombie] Starting Next.js dev server on port 3001...

No more manually killing processes or adding --port flags!

Browser Auto-Refresh

After a restart, your browser automatically refreshes when the server is ready. No setup needed!

┌─────────────────────────────────────────────────────┐
│  🧟 next-zombie v1.8.0                              │
│  Proxy ready on http://localhost:3000               │
│  Auto-refresh enabled (no setup needed!)            │
└─────────────────────────────────────────────────────┘

How it works:

next-zombie runs a proxy server on port 3000
Next.js runs internally on port 3001
The proxy automatically injects auto-refresh script into HTML
When server restarts → browser refreshes automatically!

Just open http://localhost:3000 and you're done. Press o to open browser.

Auto Install

Missing a module? next-zombie automatically runs npm install and restarts:

Module not found: Can't resolve 'lodash'

[next-zombie] Missing module: lodash
[next-zombie] Running npm install...
[next-zombie] Install completed
[next-zombie] Restarting...

This catches:

Cannot find module 'xxx'
Module not found: Can't resolve 'xxx'
Cannot find package 'xxx'

To disable: next-zombie --no-auto-install

Usage

# Default: runs 'dev' script
next-zombie

# Custom script
next-zombie start

# With arguments
next-zombie dev --port 3001

# Disable auto browser refresh
next-zombie --no-refresh

# Disable auto install
next-zombie --no-auto-install

# Keep .next cache (don't clear on restart)
next-zombie --no-clear

Options

| Option | Description | |--------|-------------| | --no-clear | Don't clear .next cache on restart | | --no-refresh | Disable auto browser refresh | | --no-auto-install | Disable auto npm install on module errors | | -h, --help | Show help message | | -V, --version | Show version number |

Package Manager Detection

next-zombie detects your package manager automatically:

Lockfile (priority): pnpm-lock.yaml → pnpm
Fallback: How you ran it (npx → npm)

So even with npx next-zombie, it runs pnpm run dev if you have pnpm-lock.yaml.

Session Report

On exit (Ctrl+C), next-zombie shows a detailed session report:

┌─────────────────────────────────────────┐
│  📊 Session Report                      │
├─────────────────────────────────────────┤
│  Uptime:    2h 15m                      │
│  Restarts:  7                           │
│  Avg interval: 19m                      │
├─────────────────────────────────────────┤
│  Errors:                                │
│  • buildManifest.tmp          (5x)      │
│  • FATAL Turbopack            (2x)      │
└─────────────────────────────────────────┘

💡 Tip: Frequent crashes may indicate Turbopack instability.
   Try: next dev --turbo=false (use Webpack instead)

The report includes:

Total uptime and restart count
Average time between crashes
Error breakdown by type (top 5)
Helpful tips based on error patterns

Requirements

Node.js >= 18.0.0
Next.js project

Contributing

Found a new error pattern that should trigger auto-restart? Open an issue!

FAQ

Q: Which Next.js versions are supported?

Next.js 13.4+ with Turbopack enabled. This includes:

13.4-14.x: When using next dev --turbo
15.x+: Turbopack is default (most useful here)
16.x+: Same Turbopack issues, same solution

If you're not using Turbopack (--turbo=false), you don't need this tool.

Q: Does this fix the Turbopack bugs?

No. It's a workaround. When Turbopack crashes, next-zombie restarts your server automatically so you don't have to.

Q: Should I use this in production?

No. This is for development only. Production builds (next build) don't have this issue.

Q: Why not just disable Turbopack?

You can! But Turbopack is significantly faster. next-zombie lets you keep that speed while handling the occasional crash.