Suraj Thallapelli

Posted on Jun 4

When a "Simple Refresh" Broke Our Production App: Next.js Static Export on Azure

#nextjs #azure #webdev #architecture

We had one of those bugs that looked small from the outside, but exposed a much deeper architecture lesson.

In our portal web application, top-level routes worked perfectly:

/registrations
/messages
/evaluations

But the moment users clicked into deeper routes like:

/registrations/available/57
/messages/123

...the entire app reloaded.

The sidebar remounted.
State was lost.
The UX felt broken.

What made this incident especially valuable was the contrast:

Locally, everything worked.
In production, it failed.

That gap turned a frustrating bug into a really useful lesson about how Next.js static export actually behaves on Azure.

The Setup

Our app was a Next.js App Router application deployed to Azure Static Web Apps using static export mode.

That meant:

No Next.js server runtime in production
No SSR at request time
No middleware execution at request time
Everything served from generated static files

We chose this model intentionally for simplicity, cost, and deployment speed.

So this was not full server-mode Next.js.

It was closer to a highly structured SPA that benefits from Next.js routing, layouts, and build output.

The Symptom

From the user's perspective:

Clicking into detail pages caused a full page refresh
Shared layout was not preserved
Sidebar reset
App state disappeared
Navigation felt unstable

From the engineering perspective, the real issue was this:

Soft navigation was failing.

The Next.js router was falling back to hard browser navigation.

That distinction ended up being the key.

What We Assumed First

At first, this looked like a classic static hosting issue:

"Maybe Azure Static Web Apps cannot resolve dynamic routes."

That was the obvious explanation.

But it was not fully correct.

Hard deep-linking often worked because rewrite shells were already in place.

The real issue was more subtle:

Hard navigation often worked
Soft navigation failed

That completely changed the debugging direction.

The Root Cause

Next.js App Router in static export mode does not only rely on generated HTML files.

For dynamic routes, it also depends on route payload files used during client-side transitions.

In simple terms:

Hard navigation needs an HTML shell
Soft navigation needs route payload data

Our Azure rewrite rule for dynamic routes was too greedy.

For example:

/registrations/* → /registrations/static_export.html

At first glance, that looked reasonable.

But the wildcard was also catching requests meant for route payload files.

So during soft navigation, when Next.js requested payload data, Azure returned HTML instead.

The router expected payload data.
It received HTML.
It could not parse the transition response.
So it fell back to full browser navigation.

That is why the entire app reloaded.

The Fix

We solved it in two layers.

1. Correct routing behavior for payload requests

We added rewrite rules so payload requests resolved to payload files, while normal page requests continued resolving to HTML shells.

2. Remove manual maintenance risk

We stopped manually editing staticwebapp.config every time a new dynamic route was added.

Instead, we generated the rewrite rules automatically from the build output.

The generator now:

Scans exported output for dynamic route artifacts
Produces both HTML and payload rewrite rules
Orders rules with the correct specificity
Writes the final staticwebapp.config into the deployment output

That turned a fragile manual config problem into a deterministic build artifact.

Why This Worked

The issue was not:

"Dynamic routes are impossible on static hosting."

The real issue was:

"Runtime payload requests were being rewritten incorrectly."

Once the rewrite rules matched what Next.js App Router actually requests during client-side transitions, the experience became stable again.

No full remount.
No sidebar reset.
No UX jump.

Biggest Lesson

Static export is not less engineering.

It is different engineering.

If you choose Next.js App Router with static export:

Treat rewrite rules as production-critical infrastructure
Understand hard navigation vs soft navigation
Understand HTML shells vs route payload files
Automate config generation from build artifacts
Do not rely on manual route mapping at scale

Practical Checklist

For teams using Next.js static export on Azure Static Web Apps:

[ ] Test deep links for every dynamic route
[ ] Test soft navigation from list pages to detail pages
[ ] Inspect network responses during client transitions
[ ] Confirm payload requests are not returning HTML
[ ] Keep rewrite rule order intentional
[ ] Generate staticwebapp.config from build output
[ ] Add CI checks for missing route artifacts
[ ] Test production-like builds early

Closing Thought

This bug looked like a simple route refresh issue.

But in reality, it was a contract mismatch between:

Next.js App Router export internals
Azure Static Web Apps rewrite behavior
Our deployment assumptions

Once those three were aligned, the fix became stable, scalable, and future-proof.

Sometimes the hardest frontend bugs are not inside the component.

They live between build output, hosting rules, and runtime navigation.

DEV Community