Next.js Deployment Issues
Overview
This playbook covers deployment failures and production-only behavior in Next.js apps.
Why It Matters
Next.js can behave differently across build, server, client, and edge contexts.
Core Concepts
- Know where the code runs.
- Build and runtime issues are different.
- Routing, caching, and environment config all matter.
Mental Models
If it works locally but fails in production, compare runtime assumptions first.
Best Practices
- Reproduce with production-like settings.
- Check build logs and runtime logs separately.
- Verify server/client boundary assumptions.
Common Mistakes
- Using browser-only APIs in server code.
- Ignoring environment differences.
- Forgetting cache or redirect behavior.
Trade-offs
More runtime awareness makes code slightly more complex, but it prevents many deployment surprises.
Decision Framework
flowchart TD
A[Deploy issue] --> B{Build failed?}
B -->|Yes| C[Check build logs]
B -->|No| D{Runtime only?}
D -->|Yes| E[Check server/client boundary and env]
D -->|No| F[Check routing or cache]Examples
- A server component using browser APIs will often fail only in production builds.
Checklists
- Did the build succeed?
- Are environment variables correct?
- Are server and client assumptions aligned?
Senior Engineer Notes
Senior engineers assume deployment is a different runtime, not just a different button.