Deploying a Four-Route Next.js App: a Setup Log

A small app should be a boring deploy. Mine was not, quite. I had four routes, a working dev server, and a pipeline that looked done. The first live load proved otherwise.

I deployed a small Next.js app, just 4 routes, through a GitHub Actions pipeline to see how clean the handoff was. The build and deploy finished in about 2 minutes, which surprised me. What did not go clean was the routing: one of the 4 pages worked fine on my laptop but came back as a 404 once it was live. It took me 2 to 3 redeploys to track it down to a trailing-slash and export-path mismatch, and only then did every route load.

The run

1. Push to the branch. The commit triggered the GitHub Actions workflow. Install, build and upload ran back to back and the whole thing was green in about 2 minutes. No caching tricks, just the default steps.
2. Open the live site. The home route and two others loaded. The fourth returned a 404. Same page had loaded on my dev server seconds earlier, so the code was not the problem.
3. Check the build output, not the code. The route that failed did not have a matching file in the exported output the way the working ones did. Locally the dev server resolves the route on the fly; the static deploy only serves what the export actually wrote to disk.
4. Fix the trailing slash. The mismatch was how the export named that route's folder versus how the live URL asked for it. Lining up the trailing-slash behaviour so the export path matched the requested path made the 404 go away.
5. Redeploy and recheck every route. It took 2 to 3 pushes before all four loaded. The lesson I took: after any export deploy, open each route by its live URL, not just the home page.

The build speed was never the issue. The gap between what runs on a dev server and what a static export actually ships is. If you are setting the pipeline up from scratch, I wrote the GitHub Actions side of this in my notes on shipping Next.js to Hostinger.