* fix(app-router): hoist streamed metadata into <head> instead of body
Async generateMetadata was serialized via dangerouslySetInnerHTML into a
hidden <div> in the body, which React cannot hoist. For JS-capable clients
(browsers, Googlebot) the tags stayed in <body>, where Google ignores
rel=canonical, hreflang and robots.
Render the resolved metadata as real <title>/<meta>/<link> elements through
MetadataHead so React 19 hoists them into <head>, matching Next.js. Remove
the now-unused renderMetadataToHtml string serializer.
* Fix tests
* fix(app-router): harden metadata hoisting coverage
* fix(app-router): restore streamed metadata placement
* fix(app-router): preserve static metadata placement
---------
Co-authored-by: James <james@eli.cx>
Dynamic App SSR currently pipes React's edge stream as soon as the shell resolves. That first pull can flush a Suspense fallback even when the boundary resolves in the next React render task, producing fallback HTML that Next avoids.
The SSR entry now marks successful dynamic streams and awaits one React render task before wiring them through the HTML transform. waitForAllReady, PPR fallback-shell, and recovered shell-error paths keep their existing behavior.
Add a stream-boundary regression that proves immediate consumption leaks the fallback marker while delayed consumption emits only the resolved content.
* fix(app-router): handle redirects in route-miss fallbacks
* test(app-router): fix frozen-lockfile break in not-found-redirect fixture
The route-miss redirect fixture shipped a package.json declaring six
"latest" dependencies (@vitejs/plugin-react, typescript, @types/react*,
vinext, vite) with no matching pnpm-lock.yaml importer. CI runs
frozen-lockfile installs, so every job died at the shared setup step with
ERR_PNPM_OUTDATED_LOCKFILE, turning the whole suite red before a single
test ran.
The fixture never needs those dependencies: dev tests load it via
createServer({ configFile: false }) with the plugin built in code, and
the production test copies it through createIsolatedFixture, which
symlinks the workspace root node_modules. The only file the build
actually reads is package.json's "type": "module" (for ESM output), so
the deps, vite.config.ts, tsconfig.json, and next-env.d.ts were all dead
scaffolding.
Trim package.json to name/private/type, add the empty lockfile importer
so frozen install is satisfied, and delete the unused config files. Also
drop app/result/page.tsx, which .gitignore's bare "result" rule silently
excluded from the commit anyway; the tests only assert the redirect
Location header, never render /result.
* fix(app-router): encode async route-miss redirects in the RSC flight
A redirect() thrown by an async root layout (one that `await headers()`
before redirecting) during a route-miss not-found render was lost on RSC
navigations. renderAppPageBoundaryResponse returns the RSC stream without
consuming it, so the async redirect only surfaced through React's onError
once the stream was pulled — after the synchronous captured-special-error
check had already run and found nothing. The request fell through to a raw
404 flight instead of the 200 flight-encoded redirect the client router
expects. The document path was unaffected because createHtmlResponse
consumes the stream, surfacing the redirect before the same check.
Drain a tee'd copy of the RSC boundary stream to force the render to
settle before the capture check, then hand the buffered copy back as the
body. Boundary responses are small terminal documents, so buffering them
is an acceptable cost for correct redirect handling; the document path is
untouched. Mirrors app-page-render.ts's pre-flush special-error capture.
Also:
- Extract the duplicated redirect-flight encoding (digest format, throwing
error, stream builder) from app-page-dispatch and app-page-boundary-render
into app-rsc-redirect-flight.ts as a single owner, with focused unit tests.
- Replace the `new Error(...) as Error & { digest }` cast with a typed
RscRedirectFlightError subclass, and read the metadata-error marker via
Reflect.get instead of an `as Record<symbol, unknown>` cast.
- Document that renderBoundarySpecialErrorResponse deliberately omits
renderFallbackPage: redirects are fully handled, but a notFound()/
forbidden()/unauthorized() re-thrown inside boundary rendering has no
parent boundary and terminates with a plain status-text response. Pin
that terminal behavior with a test.
- Add route-miss RSC redirect coverage (dev + production) asserting the
200 flight response, text/x-component, and X-Vinext-Rsc-Redirect header.
* test(app-router): prove RSC redirect drain covers matched-route fallbacks
The RSC special-error drain in the HTTP-access fallback path was described
as route-miss-only, but it runs for every http-access fallback: a matched
route's notFound()/forbidden()/unauthorized() renders its boundary through
the same path, where a layout can also async-redirect. Narrowing the drain
to route misses would leave that matched-route case with the original
lazy-stream bug, so the broad behavior is intentional.
Add a matched-route fixture page (`/gated` calls notFound()) and dev +
production coverage: with the redirect trigger the matched-route not-found's
async layout redirect is encoded as a 200 flight; without it the response is
a normal 404 flight, proving the pre-response buffering neither drops nor
corrupts the matched-route payload. Broaden the drain comment to state the
behavior spans route-miss and matched-route fallbacks and why.
* fix(app-router): honor html-limited bots for fallback metadata redirects
A redirect() thrown from generateMetadata() while rendering an HTTP-access
fallback boundary always rode as a 200 streaming response (HTML meta-refresh
/ RSC flight), even for html-limited bots that Next.js serves a blocking 307.
renderBoundarySpecialErrorResponse never passed serveStreamingMetadata, so
buildAppPageSpecialErrorResponse defaulted `serveStreamingMetadata !== false`
to streaming. Matched-page dispatch already threads
shouldServeStreamingMetadata(userAgent, htmlLimitedBots); the fallback path
did not.
Thread htmlLimitedBots into the fallback renderer, compute the same
per-request decision there, and pass serveStreamingMetadata through the
boundary options into the special-error responder. Hoist the entry's
__htmlLimitedBots declaration above __createAppFallbackRenderer (it runs at
module init) to avoid a temporal-dead-zone reference. Cover both branches:
streaming document → 200 meta-refresh, Bingbot → 307 + Location.
Also fix the matched-route drain test so it actually exercises the new path.
The prior test redirected from the root layout, which fires during the
matched-route layout probe and is caught by the layout special-error path
before the fallback renders — so it passed without touching the boundary
drain. Redirect from the route's own not-found boundary instead (on its own
header, so the root layout renders normally and the fallback is reached),
which surfaces through the RSC drain in renderAppPageBoundaryElementResponse.
* fix(app-router): prefix basePath on global-not-found fallback redirects
The global-not-found branch of renderHttpAccessFallback did not pass
basePath/trailingSlash into renderAppPageHttpAccessFallback, while the normal
fallback branch did. renderBoundarySpecialErrorResponse forwards
options.basePath into buildAppPageSpecialErrorResponse, which prefixes
app-internal redirect Locations with the configured base path. So a redirect()
thrown from app/global-not-found.tsx or its generateMetadata() produced an
unprefixed Location under basePath, unlike every other fallback boundary.
Pass basePath and trailingSlash in the global-not-found branch too, matching
the sibling branch. Also refresh the stale renderBoundarySpecialErrorResponse
comment: it described a route-miss-only path and a "root not-found or error
boundary", but the responder now covers matched-route HTTP-access fallbacks
and no longer claims error-boundary handling.
* fix(app-router): preserve fallback redirect semantics
* fix(app-router): preserve push redirect history
---------
Co-authored-by: James <james@eli.cx>
* fix(app-router): preserve raw redirect digest URLs
Redirect digests can carry raw URLs, and raw URLs can contain semicolons. Treating semicolon-delimited URL content as digest structure can truncate or misclassify the redirect target.
Keep redirect digest parsing strict about the final status segment while preserving semicolons in the URL. The server parser stays self-contained so App Router startup does not import the navigation shim.
* fix: simplify malformed redirect digest fallback
* fix: simplify malformed redirect digest fallback
* test: cover malformed redirect digest tails consistently
* fix: restore unstable rethrow cause handling
* fix: guard decodeURIComponent throw and comment status allowlist
- Wrap decodeURIComponent in try/catch for malformed lone % in raw URLs
- Add clarifying comment that only canonical 303/307/308 are extracted
- Both address ask-bonk review feedback from PR #2487
* fix(app-router): preserve raw redirect digest URLs
* fix(app-router): support empty redirect destinations
* docs(app-router): explain redirect digest formats
* docs(app-router): clarify redirect digest parsing
* test(app-router): cover redirect digest re-emission
* docs(app-router): document redirect parser invariants
---------
Co-authored-by: James <james@eli.cx>
* perf(build): filter virtual module hooks
Move several virtual-module resolveId/load hooks to Vite's object hook form with native id filters.
This lets Vite/Rolldown skip invoking vinext JavaScript handlers for unrelated module ids during dev and build module graph walks, reducing repeated string comparisons on the hot plugin hook path. The filtered hooks now only run for vinext virtual modules, instrumentation client injection, and the React canary shim ids they can actually handle.
* perf(build): anchor react canary load filter
Tighten the React canary virtual module load filter to match only the resolved null-byte-prefixed id.
I also checked exact string filters for other resolved virtual load ids, but Vite's native string filter skipped the instrumentation-client virtual module in the focused test path. Keep those null-byte virtual ids on regex filters for now.
* fix(pages): send charset=utf-8 on HTML Content-Type
Next.js serves every HTML response (SSR and prerendered) with
`Content-Type: text/html; charset=utf-8`, but vinext's Pages Router
paths sent a bare `text/html`. Without the header charset — and without
an early <meta charset> in the page — Chromium falls back to
windows-1252, so non-ASCII content renders as mojibake (e.g. nbsp as
'Â ') and the resulting DOM diverges from the hydrated tree, triggering
the full-screen hydration error overlay in dev. Reproduced against
nextjs-notion-starter-kit; baseline `next dev`/`next start` both send
the charset.
Append `; charset=utf-8` on every Pages Router HTML producer (the App
Router paths already send it):
- pages-page-response.ts — page render response headers + gSSP header
merge
- dev-server.ts — streaming SSR, ISR HIT/STALE, and static-HTML dev
responses
- pages-page-data.ts — ISR cache HIT/STALE responses in prod
- pages-request-pipeline.ts — the `defaultContentType` a buffering
adapter applies when a render response carries no Content-Type
- static-file-cache.ts — `.html` static files (prerendered pages),
matching Next.js static serving
Compression negotiation is unaffected: COMPRESSIBLE_TYPES matching
splits the media type on ";" before lookup.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(client): polyfill `global` in browser bundles
Next.js exposes the Node-style `global` alias to client code: webpack
via its `node.global` runtime shim, Turbopack by compile-time rewriting
the free `global` identifier to its globalThis shortcut and folding
`typeof global` to "object" (turbopack-ecmascript references). vinext
provided nothing, so any client dependency that reads `global` (e.g.
use-dark-mode via nextjs-notion-starter-kit) threw
`ReferenceError: global is not defined` after hydration.
Add a `vinext:client-global-define` plugin that scopes
`define: { global: "globalThis" }` to the client environment:
- builds statically rewrite free `global` references (Turbopack-style)
- dev injects `"global": globalThis` into the client runtime defines
(/@vite/env), assigning `globalThis.global` before user code runs
(webpack-style)
- the same define is layered into the client dep optimizer
(rolldownOptions.transform.define / esbuildOptions.define) because
pre-bundled deps bypass the plugin transform pipeline
`typeof global` evaluates to "object" in the browser either way,
matching Next.js. Server environments are untouched — `global` remains
the real Node global — and a user-configured `compiler.define.global`
takes precedence, mirroring Turbopack's or_insert free-var semantics.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(images): accept /_next/image/ with trailingSlash: true
With `trailingSlash: true`, the App Router dev handler 308-redirects
`/_next/image?url=...` to `/_next/image/?url=...` (the trailing-slash
normalizer runs before the image-endpoint check), but the image endpoint
only matched the exact `/_next/image` pathname — so the redirected
request 404'd and every dev-mode next/image request broke. Reproduced
on tailwind-nextjs-starter-blog, which ships trailingSlash: true.
Baseline Next 16.2.10 behaves the same way up to the redirect (dev with
trailingSlash: true also 308s `/_next/image` to `/_next/image/`) but
then SERVES the slashed form: its route matching strips a trailing
slash before matching internal paths (getItem in
packages/next/src/server/lib/router-utils/filesystem.ts), so image
requests never fail.
Match that: isImageOptimizationPath() now strips a single trailing
slash before comparing, which covers every caller — App Router
dev/prod (app-rsc-handler), Pages Router dev middleware, the Node prod
server, and the Cloudflare worker entry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: align existing assertions with charset and trailing-slash fixes
Three assertions added on main after these fixes were authored still
asserted the old behavior: bare text/html Content-Type in
static-file-cache and the pages pipeline defaultContentType, and
isImageOptimizationPath rejecting the trailing-slash form.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(config): match overlapping tsconfig paths by longest prefix
TypeScript (and Next.js) match compilerOptions.paths patterns by longest
matched prefix regardless of declaration order, but vinext materialized
them into Vite resolve.alias entries in declaration order, where the
alias plugin picks the first match. With overlapping patterns like
`"@/*": ["./src/*"]` + `"@/public/*": ["./public/*"]` (the
ixartz/Next-js-Boilerplate shape), `@/public/...` imports resolved into
src/public/ and every page 500'd.
Sort materialized aliases longest-prefix-first in both the plugin's
resolve.alias materialization and the next.config.ts loader's
runnerImport aliases.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(config): keep tsconfig path aliases out of stylesheet resolution
TypeScript compilerOptions.paths never apply to CSS in Next.js —
@import specifiers in stylesheets use standard bundler resolution,
including package.json exports maps. vinext's materialized
resolve.alias entries also ran inside Vite's internal CSS resolver
(which only consults the alias plugin plus Vite's own resolver), so a
monorepo alias like `"@scope/ui/*": ["../../packages/ui/src/*"]`
rewrote `@import "@scope/ui/globals.css"` away from its
exports-mapped target and every route failed with a postcss ENOENT in
dev, and builds failed while analyzing client references
(create-better-t-stack scaffolds).
Emit the merged alias map as alias entries and attach a customResolver
to tsconfig-derived ones that bails out for stylesheet importers
(stylesheet file paths and the synthetic <basedir>/* importer that
postcss-import/less use), letting Vite resolve the original specifier
normally. JS/TS importers keep full alias behavior — including
`import "@/styles/globals.css"` from a layout and alias-based
import.meta.glob / dynamic-import patterns, which require blind prefix
replacement. Vite 8 reports alias customResolver as deprecated during
config resolution; the replacement it suggests (a resolveId plugin)
never runs inside the CSS resolver container, so the warning is
filtered while this remains the only importer-aware hook available.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Vite 8's OXC transform (and Vite 7's esbuild transform) honour
`"verbatimModuleSyntax": true` from the app's tsconfig, so
`import { type Metadata } from "next"` leaves a side-effect
`import "next"` behind when every specifier is type-only. Next.js
(SWC) — and esbuild/tsc without verbatimModuleSyntax — elide the whole
statement. create-t3-app and other scaffolds emit both the tsconfig
option and the inline-type import form stock, so on vinext the real
Next.js server runtime was pulled into the RSC graph (dev 500
"require is not defined", build failures via styled-jsx/client-only)
and server-only modules were pulled into the browser bundle when a
"use client" file imported only types from them (t3's tRPC router
shipped to clients and crashed hydration).
Force `typescript.onlyRemoveTypeImports: false` in the oxc transform
options (and `verbatimModuleSyntax: false` in the Vite 7 esbuild
tsconfigRaw) so type-import elision matches Next.js regardless of the
app's tsconfig.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
github-actions[bot]