### What?
Two fixes for the Turbopack build tracing introduced in #90397:
1. **Don't block SSG on Turbopack shutdown**: `workerMain()` no longer awaits the shutdown promise before returning. Trace event collection is deferred to `waitForShutdown()`, which the parent process awaits *after* SSG completes. This allows static generation and Turbopack persistence/cache-flush to run in parallel.
2. **Add persistence spans to `trace-build` allowlist**: `turbopack-build-events`, `turbopack-persistence`, and `turbopack-compaction` are now included in the `to-json-build.ts` allowlist so they appear in `.next/trace-build`.
### Why?
- The `await shutdownPromise` in `workerMain()` was too eager — it prevented the caller from acknowledging the build as complete and starting SSG until Turbopack persistence finished flushing to disk.
- The persistence/compaction spans emitted by Rust (`turbopack-persistence`, `turbopack-compaction`) were not in the `to-json-build.ts` allowlist, so they were silently filtered out of `.next/trace-build`.
### How?
**`impl.ts` (worker)**:
- Removed `await shutdownPromise` from `workerMain()` — it now returns build results immediately
- `waitForShutdown()` now returns `{ debugTraceEvents }` after awaiting shutdown, so trace events are collected only after all compilation events (including persistence spans) have been processed
**`index.ts` (parent)**:
- Moved `recordTraceEvents(debugTraceEvents)` from the `workerMain` result handler into the `shutdownPromise` `.then()` chain, so events are replayed into the parent reporter after shutdown completes
**`to-json-build.ts`**:
- Added `turbopack-build-events`, `turbopack-persistence`, `turbopack-compaction` to the allowlist
**Test updates**:
- Enabled `turbopackFileSystemCacheForBuild: true` in the trace-build test fixture
- Updated the Turbopack inline snapshot to include `turbopack-build-events`
After a successful, Turbopack production build, this writes
`.next/diagnostics/route-bundle-stats.json`
containing First Load JS stats for every route.
## Why?
We used to have route bundle size statistics print after every build. It
was not very high-signal and could be misleading, often using heuristics
to give a best-effort estimate of what sizes may be at runtime. **These
kinds of metrics for route bundle sizes can be misleading, as pages can
be slow to visual/interactive completeness even if they have small first
load bytes.**
However, a minimal gauge of how much JavaScript a route ships during
initial page load can be a useful signal so long as users have
additional context and awareness of their app structure. Let's provide
just this number for now for those that could benefit.
Additionally, this does so in the form of writing a json document to the
build directory, rather than writing a table to stdout, where users have
needed to write extra tools to parse.
## Format
An array of route entries sorted descending by
`firstLoadUncompressedJsBytes`:
```json
[
{
"route": "/blog/[slug]",
"firstLoadUncompressedJsBytes": 124928,
"firstLoadChunkPaths": [
".next/static/chunks/framework.js",
".next/static/chunks/main.js",
".next/static/chunks/pages/blog/[slug].js"
]
}
]
```
`firstLoadUncompressedJsBytes`: sum of uncompressed sizes of all JS
chunks loaded on first navigation to the route (shared chunks included),
for both Pages Router and App Router
`firstLoadChunkPaths`: paths to those chunks relative to the project
root
## Test Plan
Added an integration test. Built with a create-next-app and verified the
json document is written and the numbers align with what Chrome reports
during initial load of a page.
Initial version of build-time instant validation.
During prerendering, if we have `unstable_instant` configs, we perform a
complete staged render of the page (including dynamic data). This render
mocks request data (`params`/`searchParams`/`cookies`/`headers`) using
the `samples` provided in `unstable_instant`. Then, we use the staged
chunks to run instant validation in mostly the same way that we would in
dev. Most changes in the validation flow are related to samples, which
also need to be passed into the client render to mock APIs like
`useParams`.
### Providing Mock data
We run everything in a fresh workStore+workUnitStore to (hopefully)
avoid any data from the prerender from sneaking in. This is quite
involved.
A big part of the trickiness is that if you do e.g. `(await
cookies()).get('myCookie')` but the `samples` don't contain `myCookie`,
we want the validation to error and require explicitly saying what state
`myCookie` is in.
If it's available, use
```ts
export const unstable_instant = {
// ...
samples: { cookies: [{ name: "myCookie", value: "someValue" }] }
}
```
If it's not available, use
```ts
export const unstable_instant = {
// ...
samples: { cookies: [{ name: "myCookie", value: null }] }
}
```
This explicitness makes it harder to e.g. unintentionally validate a
logged-out state.
Note that even validating a `prefetch: 'static'` page might require
samples, because we need the shared parent for the navigation to be
(mostly) complete. We might be able to relax this in the future, but
it's not straightforward.
Another issue is that a segment might access a missing sample in a
"benign" way, i.e. where it wouldn't block validation (or be inside a
suspense boundary). Ideally we wouldn't require providing a sample for
usages like that, but currently we do.
### Instrumenting APIs to detect missing samples
All request APIs are instrumented in this way.
- `params` throw when accessing a property that was not declared in
`samples`. same for the object from `useParams()`. `in` is allowed
because we know the shape of the params object statically, based on the
routing structure.
- `searchParams` throw when accessing a property that was not declared
in `samples` and `in` checks.
- objects returned from `cookies()`, `headers()`, `useSearchPrams()`
throw on `get()` and `has()`.
There's a lot of tests for this behavior in `instant-validation-build`.
One gap is that iteration/enumeration is currently not instrumented.
We're punting on it for now and will revisit in a follow-up.
### Relation to prerender
We kick off the validation after the prerender, in
`renderToHTMLOrFlightImpl`. Ideally, we should kick this off somewhere
higher up, separately from the prerender itself, but we're leaving that
for future work.
Note that if we do multiple prerenders for the same page (e.g. due to
`generateStaticParams`, we'll only run validation for the first
prerender for that route. `generateStaticParams` is not currently
integrated into the validation at all, i.e. we don't use those params to
validate, so this is safe. All params need to be provided via `samples`.
This will likely change in the future, but we're not sure how yet.
### Disabling build validation
Build-time instant validation is experimental, and has more potential
problems to deal with than dev validation. To allow incremental rollout
and testing, we allow disabling it per instant config:
```ts
export const unstable_instant = {
unstable_disableBuildValidation: true
// ...
}
```
for parity, there's also `unstable_disableBuildValidation`, but we don't
expect that to see much use.
The recent Cached Navigations feature introduced navigation-level
caching into the segment cache, where static and dynamic RSC data from
navigations and initial HTML loads is cached so that repeat visits can
be served instantly. This feature is currently gated behind
`cacheComponents`, meaning it activates for all projects that enable
Cache Components.
This change introduces a new `experimental.cachedNavigations` flag that
independently controls the Cached Navigations behavior. The flag
defaults to `false` so we can investigate potential regressions that the
feature might have introduced without affecting the broader Cache
Components functionality.
The flag requires `cacheComponents` to also be enabled and throws a
configuration error if `cachedNavigations` is set without it. On the
server, the staged rendering paths in `app-render.tsx` (both RSC request
handling and initial HTML rendering) now check `cacheComponents &&
cachedNavigations` before producing staged responses. On the client,
`process.env.__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS` is used alongside
`process.env.__NEXT_CACHE_COMPONENTS` for compile-time dead code
elimination in the stream tee (`app-index.tsx`) and the response
processing (`fetch-server-response.ts`).
The cached navigations test suite enables the flag via `next.config.ts`,
and the Cache Components CI jobs export
`__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS=true` to maintain test coverage.
This makes sure we don't have assertions that will only pass in one
environment e.g. these should work for running against bun and not just
node or against a local metadata URL not just a deployed https fully
qualified domain. Ensures others can leverage this test suite for their
own verification easily.
## Summary
- Adds `cleanupScriptPath` workflow dispatch input and
`NEXT_TEST_CLEANUP_SCRIPT_PATH` env var to `test_e2e_deploy_release.yml`
(webpack + turbopack jobs)
- Adds `cleanupUsingCustomScript()` method to `NextDeployInstance`
following the same pattern as the existing deploy and logs scripts
- Calls the cleanup script in `destroy()` before existing teardown logic
---------
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
This allows specifying a different deployment id for static immutable assets
- [x] rename `getImmutableAssetToken` to `getAssetToken` (because it can be non-immutable as well)
- [x] disable for webpack
Closes PACK-6534
For https://github.com/nextjs/adapter-vercel/pull/25
Part of PACK-6802
Enable skew protection for all start-mode tests when Turbopack is enabled (i.e. not dev). This works by setting `NEXT_DEPLOYMENT_ID` in the test infra
- When running the tests, `packages/next/src/server/lib/router-utils/resolve-routes.ts` now validates that all static asset requests have the correct `?dpl=...` query param value, and returns a 404 if missing.
- It can be disabled with `disableAutoSkewProtection: true` in the test options
- There were various tests that were asserting URLs and were missing the optional `?dpl` at the end.
- `next.getDeploymentIdQuery()` can be used to get the `?dpl=dpl_123912js` string (or an empty string)
- `next.getAssetQuery()` currently behaves like `getDeploymentIdQuery`, but will switch to prefer the immutable static token in #88607
`run-tests.js` explicitly unsets `CI` in the spawned Jest child process
and preserves the original value as `NEXT_TEST_CI`. Since
`test/lib/e2e-utils/index.ts` runs inside that child process,
`process.env.CI` is always empty, making the `jest.retryTimes(1)` call
effectively dead code in CI.
The 500ms settling period in router-act's `act()` polled for 500ms after
the request queue emptied before exiting. This was added to accommodate
the 300ms revalidation cooldown in the client router — after a server
action calls `revalidatePath`/`revalidateTag`, the client delays
re-prefetching for 300ms. The settling period ensured `act()` waited
long enough to catch the resulting re-prefetch.
The settling period applied to every `act()` call, not just ones
involving revalidation, adding ~500ms per call across 28 test files.
Remove it entirely and instead use Playwright's fake clock
(`page.clock.install` / `page.clock.fastForward`) in the revalidation
tests to deterministically control the cooldown. This is both faster and
architecturally cleaner — the test utility no longer embeds knowledge of
a specific client-side timer.
*This doesn't enable skew protection for any new tests, only preparation*
Prepare a lot of test assertions so that they work correctly when a `?dpl=123` query param is present:
- some regexes should accept the query
- some places assumed that the `<script>`'s `src` is a valid pathname, whereas it might have a query param that has to be stripped before removing the path
- some hardcoded build ids instead of `next.buildId`
The per-test `jest.retryTimes(1)` added in #89929 is useful for CI
resilience & performance but produces confusing logs and adds
unnecessary wait time when investigating test failures locally.
We're now only enabling the retry when running in CI so that local runs
fail fast on the first attempt.
If the trimmed error message has no length, we skip the line entirely to remove useless vertical space from the Redbox. Errors with no messages are assumed to only be relevant due to their stack.
Before:
```
apiRequestContext.fetch: Request timed out after 30000ms
Call log:
- → GET http://localhost:55200/refetch-on-new-base-tree/a?_rsc=1u5ob
- <snip>
225 | // server; we pass the request to the server the immediately.
226 | result: (async () => {
> 227 | const originalResponse = await page.request.fetch(request, {
| ^
228 | maxRedirects: 0,
229 | })
230 |
at fetch (lib/router-act.ts:227:59)
at lib/router-act.ts:245:13
at routeHandler (lib/router-act.ts:257:7)
```
After:
```
apiRequestContext.fetch: Request timed out after 30000ms
Call log:
- → GET http://localhost:61662/refetch-on-new-base-tree/a?_rsc=1u5ob
- <snip>
264 |
265 | // Reveal the links to trigger prefetches
> 266 | await act(async () => {
| ^
267 | await linkALinkVisibilityToggle.click()
268 | await linkBLinkVisibilityToggle.click()
269 | }, [
at Object.act (e2e/app-dir/segment-cache/revalidation/segment-cache-revalidation.test.ts:266:11)
```
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
- Edge Runtime was missing `globalThis.NEXT_CLIENT_ASSET_SUFFIX` at runtime
- Prerenders were always running `globalThis.NEXT_CLIENT_ASSET_SUFFIX` set
Fixups after #88828
This PR speeds up the `instant-validation` test suite from 450s down to
~100s. We were wasting a lot of time in `waitForNoErrorToast()`, which
ends up waiting almost 15s by default.
The trick is to add some debug logs inside app-render to track when
instant validation started/ended. If we know that the validation is
finished, we can just wait for a short time, because if there were
errors, a toast would be displayed very quickly.
Note that is a stopgap -- when we add a "Validating..." indicator, we
won't have to emit the log and can just wait for the indicator instead.
But in the meantime, waiting for the tests is pretty painful, so this is
worth doing.
This should reduce some duplicate CI jobs.
This split existed to support separate dev/prod manifests for skipping tests. That's not needed anymore, so we can just switch to the Webpack setup. This manual partitioning of `integration` tests into dev vs prod was brittle anyway
We still need this setup for rspack though
Flagged behind `experimental.appNewScrollHandler`
`focus()` on Fragment refs works different than `findDOMNode(this).focus()`.
`findDOMNode` will return an actual host element so it's effectively `HTMLElement.focus()`. If the element isn't focuseable, `focus()` will do nothing. By spec, there's also no way to determine if an element is focusable. It's up to user agents (e.g. sometimes scrollable containers are considered focusable).
`FragmentInstance.focus` will focus the first focusable descendant. That could be a focusable element deep within the fragment e.g. `<Fragment><section><p>A lot of text</p><a href="">Next page</a></Fragment>`. Focusing such a deep element may sometimes be counter productive.
Now we just blur the active element. This is how a hard navigation already works today and ensures we don't skip past content of the new segment.
This means you potentially stay a long way before the actual Segment (e.g. in a preceding nav) with the focus cursor which could be annoying. We could be clever and temporarily insert a focusable element at the start of the Segment, focus it, and then immediately remove. That would leave the focus cursor right before the Segment. However, this requires knowledge about the parent content (can we just insert an element of our choosing?) and relies on knowing what's focusable (a button would be a good bet). That's a bit too clever for a fix without concrete motivation so I'm waiting somebody to complain about the new behavior.
Fork the set of deployment tests so they run with both turbopack and
webpack. Now that turbopack is the default bundler we need this
coverage.
Because we are now running twice as many tests, decrease concurrency,
otherwise we hit rate limits on vercel. There were attempts to improve
rate limit recovery in the vercel CLI
(https://github.com/vercel/vercel/pull/14443 and
https://github.com/vercel/vercel/pull/14407) which helped but did not
solve the issue. Also there was an investigation into the API service
where we discovered some suspicious but ultimately correct code
(https://github.com/vercel/api/pull/55967).
The basic issue is that the vercel CLI polls `api-deployments-get`
fairly aggressively at the beginning of a deploymnet, and since we start
so many deployments in parallel we will always hit the rate limits. The
recovery logic in the CLI is good but has (reasonably) a fixed set of
retries it will attempt, inevitably some tasks get unlucky. So retrying
the test does work, but really we should slow down which is what we do
here. 😥https://github.com/vercel/next.js/actions/runs/20290161194/job/58272593085
Fixes PACK-5613
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
This aims to avoid us having tests stall for upwards of 240s when a
single assertion in the test stalls. This is very common currently. To
also avoid wasting the entire time of resetting the test suite this also
allows 1 retry for individual failed assertions. This won't always work
since some assertions rely on previous setup so this also keeps the
entire test suite retry handling as a fallback.
This change is not applied for dev tests as they check HMR and compile
lazily.
## Summary
- keep elevated Jest timeout for test setup/startup in e2e-utils
- enforce a 60s default timeout for individual `it`/`test` cases
- apply one retry per individual test via `jest.retryTimes(1)`
## Verification
- pnpm testonly test/development/gssp-notfound/index.test.ts
- pnpm testonly test/development/enoent-during-require/index.test.ts
- pnpm testonly test/e2e/custom-app-render/custom-app-render.test.ts
Tested against our deploy tests to see if this helps:
Current run
[21967823508](https://github.com/vercel/next.js/actions/runs/21967823508)
Jobs: 24 (with test-runner output: 20)
Whole-suite retry starts: 11 (retry 1: 8, retry 2+: 3)
Jobs that needed suite retries: 8
Unique test files retried: 7
Previous run
[21964085768](https://github.com/vercel/next.js/actions/runs/21964085768)
Jobs: 26 (with test-runner output: 20)
Whole-suite retry starts: 18 (retry 1: 13, retry 2+: 5)
Jobs that needed suite retries: 9
Unique test files retried: 12
Just plumbing and enabling that flag in the experimental shards. The flag will enable our Layout router to use Fragment refs for scroll restoration. Implementation will be done in a follow-up.
## Summary
Adds support for custom deploy scripts in the `next-deploy` test mode
via two new environment variables:
- `NEXT_TEST_DEPLOY_SCRIPT_PATH` - Path to a custom script that deploys
the project and outputs the deployment URL to stdout
- `NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH` - Path to a custom script that
fetches build logs (required when using custom deploy script)
This allows running deploy tests against non-Vercel deployment targets.
### Priority Order
1. `NEXT_TEST_DEPLOY_URL` - If set, uses existing deployment (no deploy
happens)
2. `NEXT_TEST_DEPLOY_SCRIPT_PATH` - If set, uses custom deploy script
3. Default Vercel CLI logic - If neither is set
### Script Interface
**Deploy script** receives:
- `NEXT_TEST_DIR` - The test directory containing the Next.js project
- All test-specific environment variables
- Must output deployment URL to stdout
**Logs script** receives:
- `NEXT_TEST_DIR` - The test directory
- `NEXT_TEST_DEPLOY_URL` - The deployment URL
- Must output build logs containing `BUILD_ID: <id>` pattern
Verified existing flow is still working in:
https://github.com/vercel/next.js/actions/runs/21465304133
This updates to run the entire E2E deploy tests same as we do currently
but with adapters enabled to catch regressions there. These run on a
separate test team to isolate from existing test team and avoid rate
limits.
Test run of the workflow done here
https://github.com/vercel/next.js/actions/runs/21418745794
This applies fixes for outputs in `onBuildComplete` with various slight
differences from expected values. This also applies some fixes in the
route-module interface to ensure we install the process handlers for PPR
since currently that was done in `next-server` which we want to get rid
of and there was an edge case with query parsing logic in the
route-module.
Our E2E tests were run against this here to validate
https://github.com/vercel/next.js/actions/runs/21324578779 and failures
are matching existing failures on canary.
x-ref: https://github.com/nextjs/adapter-vercel/pull/11
x-ref: https://github.com/vercel/vercel/pull/14574
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
## Summary
Implements an LRU cache with compound keys for the minimal mode response
cache to improve cache hit rates during parallel revalidation scenarios.
**Problem**: The previous single-entry cache (`previousCacheItem`) keyed
by pathname caused cache collisions when multiple concurrent invocations
(e.g., during ISR revalidation) accessed the same pathname. Each
invocation would overwrite the previous entry, leading to cache misses
and redundant work.
**Solution**: An LRU cache using compound keys (`pathname +
invocationID`) that allows multiple invocations to cache entries for the
same pathname independently:
```
Cache Key Structure
─────────────────────
/blog/post-1\0inv-abc → {entry, expiresAt}
/blog/post-1\0inv-def → {entry, expiresAt}
/blog/post-1\0__ttl__ → {entry, expiresAt} (TTL fallback)
/api/data\0inv-ghi → {entry, expiresAt}
```
### Cache Key Strategy
- **With `x-invocation-id` header**: Entries are keyed by invocation ID
for exact-match lookups (always a cache hit if the entry exists)
- **Without header (TTL fallback)**: Entries use a `__ttl__` sentinel
key and validate via expiration timestamp
### Configuration via Environment Variables
Cache sizing can be tuned via environment variables (using
`NEXT_PRIVATE_*` prefix for infrastructure-level settings):
| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `NEXT_PRIVATE_RESPONSE_CACHE_MAX_SIZE` | 150 | Max entries in the LRU
cache |
| `NEXT_PRIVATE_RESPONSE_CACHE_TTL` | 10000 | TTL in ms for cache
entries (fallback validation) |
### LRU Cache Enhancement
Added an optional `onEvict` callback to `LRUCache` that fires when
entries are evicted due to capacity limits. This enables tracking
evicted invocation IDs for warning detection without introducing
timer-based cleanup.
### Eviction Warnings
When a cache entry is evicted and later accessed by the same invocation,
a warning is logged suggesting to increase
`NEXT_PRIVATE_RESPONSE_CACHE_MAX_SIZE`. This helps developers tune cache
sizes for their workload.
### Additional Changes
- Renamed header from `x-vercel-id` to `x-invocation-id` for clarity
- Added `withInvocationId()` test helper for cache testing
## Test Plan
- Existing response cache tests pass with updated header name
- Unit tests for `LRUCache` including `onEvict` callback behavior
- Updated standalone mode tests to use `withInvocationId()` helper
When digging into failing deployment tests, I often will re-run the test
itself without wanting to change anything about Next.js or the test
application, especially when I suspect a logic bug in the test itself or
need to figure out what's causing a flake.
This adds an environment variable that can be used to skip the
build/deploy step and will use an existing deployment URL to run the
tests against.
I suggest reviewing this [without
whitespace](https://github.com/vercel/next.js/pull/88829/changes?w=1).
Closes PACK-6539
When `experimental.runtimeServerDeploymentId` is enabled, read the `process.env.NEXT_DEPLOYMENT_ID` and append to the chunks when evaluating the `client-reference-manifest.js`
Originally, I tried to do it after the manifest is loaded (in `loadComponents` or in the `RouteModule.prepare`) to "hydrate" the manifest, but that is too late because the manifest needs to be initialized immediately to make module-evaluation-time server actions work (which need the manifest immediately)
This change ensures that the `buildArgs` specified in `nextTestSetup` are also applied when running deploy tests. This is achieved by modifying the build command in the `package.json` file used for deploy tests to include the specified `buildArgs`.
See also https://vercel.com/docs/builds/configure-a-build#build-command.
The only current e2e test that uses the `buildArgs` option is `test/e2e/react-compiler/react-compiler.test.ts`, but that one is excluded from deploy tests via `deploy-tests-manifest.json`.
The file already had the `@ts-check` directive, so the IDE did show errors in that file. But since it was not included in the root `tsconfig.json`, those errors were not reported during CI runs.
One issue found this way was that the `related` flag was defined but never used. The referenced script was removed in #67644.
Sebastian "Sebbie" Silbermann