Cloud & DevOps
Deploying a Next.js Static Export to cPanel Without Surprises
8 min read
Next.js can produce a fast, portable static site for ordinary shared hosting, but only when the app is designed around build-time routes and browser-side interactions from the start.
Accept the static boundary
Set the project to static export and treat the generated output as the deployable artifact. Server Actions, request-time cookies, API routes, rewrites, and the default image optimizer need a running Next.js server, so they do not belong in this hosting model.
Dynamic routes still work when every valid value is returned from generateStaticParams. This is ideal for services and blog posts stored in local data because the build can produce one directory per slug.
- Use output export in the Next configuration
- Return every blog and service slug at build time
- Set dynamicParams to false for closed collections
- Keep form submissions on a suitable external endpoint
Generate Apache-friendly paths
Shared hosting commonly serves directory indexes reliably. Enabling trailing slashes produces paths such as blog/post/index.html, which avoids depending on extension rewrite rules. Use the same trailing-slash convention in canonical URLs and internal links.
Static images belong in public and need to be compressed before committing because there is no on-demand optimizer. Provide intrinsic dimensions or a stable aspect-ratio container so the layout does not jump.
- Test direct navigation to nested routes
- Upload the contents of out, not the out folder itself
- Verify MIME types for generated images and fonts
- Include the generated 404, sitemap, and robots files
Make deployment repeatable
Run linting, a separate TypeScript check, and the production build before uploading. Keep the previous release in a dated backup directory or archive so rollback means restoring files, not debugging under pressure.
After deployment, test the live domain with a private window. Confirm nested URLs, forms, downloads, social previews, and mobile navigation. A green local build cannot detect a wrong document root or stale hosting cache.
- Document the domain-to-folder map
- Do not upload development servers or secret files
- Use HTTPS before testing browser crypto or payments
- Compare a small manifest of expected routes after every release