mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
Wyatt JohnsonandGitHub
3630146458
### What?
Adds build-time validation to require explicit `default.js` files for
all parallel route slots (except the implicit "children" slot). This
validation is implemented in both Webpack and Turbopack bundlers.
### Why?
Parallel routes without `default.js` files currently cause silent 404
errors when users navigate to those routes. This creates confusion and
hard-to-debug issues because the routes appear to be configured
correctly but fail at runtime without any indication of what went wrong.
By making this validation explicit at build time, developers get
immediate feedback about missing required files with clear error
messages and documentation links, catching configuration mistakes before
deployment.
### How?
**Rust/Turbopack** (`crates/next-core/src/app_structure.rs`): Added
`MissingDefaultParallelRouteIssue` that emits a build error when a
parallel route slot is missing its `default.js` file. The validation is
skipped for the "children" slot since it's implicit and doesn't require
a default file.
**Webpack**
(`packages/next/src/build/webpack/loaders/next-app-loader/index.ts`):
Added validation that throws `MissingDefaultParallelRouteError` when
`default.js` cannot be resolved. The "children" slot falls back to the
existing `PARALLEL_ROUTE_DEFAULT_PATH` behavior for backward
compatibility.
**Error Class**
(`packages/next/src/shared/lib/errors/missing-default-parallel-route-error.ts`):
New error type with helpful messaging that includes the slot path,
explanation of the requirement, and a link to documentation.
**Migration Path**: Users who want the previous 404 behavior can
explicitly create a `default.js` that calls `notFound()`, or return
`null` for empty slots:
```tsx
import { notFound } from 'next/navigation'
export default function Default() {
notFound()
}
```
Users can also run the following Deno script to generate the default
files for them:
https://gist.github.com/wyattjoh/ba7263ecb637ef399d3e3e4db63ffbd6
**Breaking Change**: This is a breaking change timed for Next.js 16
beta. Builds will now fail if parallel route slots are missing required
`default.js` files.
81 lines
2.7 KiB
Plaintext
81 lines
2.7 KiB
Plaintext
---
|
|
title: Missing Required default.js for Parallel Route
|
|
---
|
|
|
|
> Parallel route slots require a `default.js` file to serve as a fallback during navigation.
|
|
|
|
## Why This Error Occurred
|
|
|
|
You're using [parallel routes](https://nextjs.org/docs/app/api-reference/file-conventions/parallel-routes#defaultjs) in your Next.js application, but one of your parallel route slots is missing a required `default.js` file, which causes a build error.
|
|
|
|
When using parallel routes, Next.js needs to know what to render in each slot when:
|
|
|
|
- Navigating between pages that have different slot structures
|
|
- A slot doesn't match the current navigation (only during hard navigation)
|
|
- After a page refresh when Next.js cannot determine the active state for a slot
|
|
|
|
The `default.js` file serves as a fallback to render when Next.js cannot determine the active state of a slot based on the current URL. Without this file, the build will fail.
|
|
|
|
## Possible Ways to Fix It
|
|
|
|
Create a `default.js` (or `.jsx`, `.tsx`) file in the parallel route slot directory that's mentioned in the error message.
|
|
|
|
For example, if you have this structure where different slots have pages at different paths:
|
|
|
|
```
|
|
app/
|
|
├── layout.js
|
|
├── page.js
|
|
├── @team/
|
|
│ └── settings/
|
|
│ └── page.js
|
|
└── @analytics/
|
|
└── page.js
|
|
```
|
|
|
|
You need to add `default.js` files for each slot, excluding the children slot:
|
|
|
|
```
|
|
app/
|
|
├── layout.js
|
|
├── page.js
|
|
├── default.js // Optiona: add this (for children slot)
|
|
├── @team/
|
|
│ ├── default.js // Add this
|
|
│ └── settings/
|
|
│ └── page.js
|
|
└── @analytics/
|
|
├── default.js // Add this
|
|
└── page.js
|
|
```
|
|
|
|
Without the root `default.js`, navigating to `/settings` would result in a 404, even though `@team/settings/page.js` exists. The `default.js` in the root tells Next.js what to render in the children slot when there's no matching page at that path. It's not required as other named slots default files are, but it's good to add to help improve the experience for your applications.
|
|
|
|
### Example `default.js` file:
|
|
|
|
The simplest implementation returns `null` to render nothing:
|
|
|
|
```jsx filename="app/@analytics/default.js"
|
|
export default function Default() {
|
|
return null
|
|
}
|
|
```
|
|
|
|
You can also preserve the old behavior of returning a 404:
|
|
|
|
```jsx filename="app/@team/default.js"
|
|
import { notFound } from 'next/navigation'
|
|
|
|
export default function Default() {
|
|
notFound()
|
|
}
|
|
```
|
|
|
|
### When you need `default.js`
|
|
|
|
You need a `default.js` file for each parallel route slot (directories starting with `@`) at each route segment.
|
|
|
|
## Useful Links
|
|
|
|
- [Parallel Routes Documentation](https://nextjs.org/docs/app/api-reference/file-conventions/parallel-routes#defaultjs)
|