Deployment field guide
Deploying Next.js Static Sites Without Build Surprises
Static export is strict in a useful way: it exposes hidden assumptions before your users do.
Portfolios and content sites are excellent static-export candidates. The tradeoff is simple: Next.js must be able to produce every page without waiting for a future request.
01 / DETERMINISTIC ROUTES
Tell the build which dynamic pages exist
A route such as /projects/[slug] represents many possible URLs. In export mode the build cannot guess those values, so generateStaticParams() provides the complete list.
export function generateStaticParams() {
return projects.map((project) => ({
slug: project.slug,
}));
}02 / FAILURE PATTERNS
Most “random” failures are mismatches
A card may link with a slug while the detail page searches by id. An asset may work on a case-insensitive laptop but fail on a Linux server. A route may read request headers even though export mode has no request.
Watch the contract between files
Route folder, generated parameter, link href, and data lookup must all agree on the same name and value.
03 / THE WORKFLOW
Build before deployment day
Development mode optimizes for feedback and can hide export-only problems. Run a production build whenever you add a route, change content structure, or introduce an integration. Small, frequent verification makes the failing change obvious.
The takeaway
Static export rewards clear boundaries.
When URLs, content, assets, and rendering requirements are deterministic, the site becomes fast, portable, and easy to host almost anywhere.