cloudflare / cloudflare/vinext

App Router: align explicit parallel-route children and strict route matching

Open
#3,122 0 comments 0 reactions 0 assignees View on GitHub
nextjs-tracking
Dominant language
TypeScript
Stars
8.8k
Forks
406
Avg merge
2d 6h
Merged PRs (30d)
120

Description

## Next.js Change

**Commits:**

- [`05ed7c1`](https://github.com/vercel/next.js/commit/05ed7c1be263cc86496be4a65a50aa9599112303) ([#97184](https://github.com/vercel/next.js/pull/97184))
- [`6d6228c`](https://github.com/vercel/next.js/commit/6d6228c0c6513718a517965c55d2d444f14ac842) ([#97108](https://github.com/vercel/next.js/pull/97108))

## What changed

Next.js now includes a `children` parallel-route branch only when an ordinary filesystem branch reaches a `page` or `default`; layouts alone and named-only route trees do not synthesize it. This behavior is enabled by default through `experimental.explicitParallelRouteChildren`, with `false` retaining the legacy synthetic-children fallback.

It also adds opt-in `experimental.strictRouteMatching`. When enabled, matchers that can only construct a permanent not-found tree because a declared parallel slot lacks a matching page or default are omitted. Complete named-only trees, explicit defaults, and route-specific sibling matches remain routable.

## Impact on vinext

Vinext App Router route-tree generation must distinguish declared ordinary `children` branches from named-only parallel layouts. It also needs the strict matching behavior so requests and soft navigations do not select a partial parallel-route tree that can only render not-found.

## Acceptance criteria

- [ ] Omit synthesized `children` from named-only parallel layouts unless an ordinary descendant reaches a `page` or `default`, including through nested parallel slots.
- [ ] Preserve the legacy synthetic `children` behavior when `experimental.explicitParallelRouteChildren` is `false`.
- [ ] Support opt-in `experimental.strictRouteMatching` and omit only incomplete route matchers.
- [ ] Retain complete matchers: named-only routes where every slot matches, user-authored defaults, and concrete siblings of pruned catch-all or optional-catch-all routes.
- [ ] Verify direct requests and client navigation have matching not-found behavior for pruned routes.
- [ ] Add focused fixture coverage for named-only layouts, nested parallel routes, defaults, catch-alls, and route groups.

## Related

- #1369 - Intercepted and parallel-route state retention; do not duplicate its traversal/refresh restore work
- vercel/next.js#97242 - Follow-on interception host-slot retention change already covered by #1369

Contributor guide

Open the contributing guide

Research direction

Start at vinext's App Router route-tree generation and its existing fixture coverage, then compare the requested behavior with #1369 without duplicating its traversal or refresh-restore work. Done means explicit children and strict matching follow the acceptance criteria, with direct requests and client navigation agreeing on not-found behavior across the listed route fixtures.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
frontend, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.