The default.js Convention

The critical fallback for Parallel Routes on hard reload.

Next.js5 min readConcept 13 of 65

The parallel fallback

The default.js file is highly specialized: it is used *exclusively* in conjunction with Parallel Routes (slots named with an @ prefix, like @modal or @analytics).

It serves as a fallback UI for a parallel slot when Next.js doesn't know what else to render for that specific slot based on the current URL.

The hard reload problem

When a user navigates around your app using Next.js Links (client-side navigation), unmatched parallel slots simply remember and keep rendering whatever they were showing previously.

But if the user hits **Refresh** (a hard reload), the server must rebuild the page from scratch. The server has no memory of previous client state. If the current URL doesn't match any specific folder inside a parallel slot, Next.js panics and throws a 404 error.

Returning null

To fix this, you drop a default.js file into your slot folder (e.g., app/@modal/default.js).

When the server encounters an unmatched slot during a hard reload, it will render the default.js instead of throwing a 404. In many cases—especially for things like modals—your default.js will simply return null; to render nothing.

The Hard Reload Trap

Study the diagram. Notice how client-side navigation (clicking a Link) is perfectly safe, but hitting the Refresh button forces the server to rebuild. Without a default.js, the server panics and throws a 404.

Client Navigation

Using <Link>

User actionClicks /settings link
Next.js Router (Browser)
Updates URL to /settings
Fetches settings UI
Preserves unmatched @modal state
Success! No fallback needed.

Hard Reload

Browser Refresh

User actionHits Refresh on /settings
Next.js Server (Node)
Builds /settings UI
Has no memory of @modal state. Must rebuild it from scratch.
Without default.jsServer panics. Cannot resolve slot. Throws 404 Error.
With default.jsServer renders the fallback UI. Page loads perfectly.

Parallel routes (like @modal) maintain their active state during normal client-side navigation. However, if a user hits Refresh, the server must reconstruct the entire page. If the current URL doesn't explicitly match a sub-route inside the @modal folder, Next.js requires a default.js file as a fallback, otherwise it throws a 404.

Check yourself

Pick an answer to lock it in, then read why. Getting one wrong is part of how it sticks.

  1. 1Under what specific condition does Next.js look for a default.js file in a parallel route?
  2. 2If you are using a parallel route (@modal) to show a popup window, what should @modal/default.js usually return?

Remember this

  • default.js is only used with Parallel Routes (slots).
  • It prevents 404 errors on hard reloads (page refreshes).
  • It acts as a fallback when the current URL doesn't match a route inside the slot.
  • For modals, default.js often just returns null.

Done with this concept?

Mark it complete to track your progress. No login needed.