## Summary
- Fixes flaky test "per-page value overrides global staleTimes.dynamic
regardless of direction" introduced by #91437
- The test was flaky because `browser.back()` restored accordion state
from BFCache, causing previously-opened `LinkAccordion` links to be
immediately visible. This triggered uncontrolled re-prefetches outside
the `act` scope. When the `IntersectionObserver` fired inside a
subsequent `act` scope (after clock advancement), stale data would
trigger a prefetch that violated the `no-requests` assertion.
- Fix: instead of navigating back to a previously visited page, navigate
forward to fresh "hub" pages with their own `LinkAccordion` components.
Since these are never-visited pages, accordions start closed and no
uncontrolled prefetches are triggered.
- General principle: when using the router `act` test utility, always
use `LinkAccordion` to control when prefetches happen. Prefetches should
only be triggered inside an `act` scope by toggling an accordion, never
by navigating back to a page where links are already visible.
## Test plan
- [x] Ran the full test file 4 times locally — all 5 tests pass
consistently
#89819 has been causing a lot of pain for me, because I often have already compiled a version of Turbopack, usually with a custom profile or set of flags, and then I want to just compile the JS bits, but there's no way for me to do it without also recompiling Turbopack again, because the `maybe-build-native` doesn't understand my custom-built binary.
This reverts the behavior of `pnpm build`, but adds a `pnpm build-all` command for people who want this automatic compilation behavior (e.g. agents?).
## What?
Adds a `maybe-build-native.mjs` script to `packages/next-swc/` that conditionally rebuilds native SWC bindings during `pnpm build`. The script is integrated into the turborepo pipeline as the `build` task for `@next/swc`.
## Why?
Developers often forget to run `pnpm swc-build-native` after pulling Rust changes, leading to confusing runtime errors. Conversely, rebuilding native binaries when nothing changed wastes significant time. This automates the decision so `pnpm build` always does the right thing.
## How?
The `maybe-build-native.mjs` script runs as `@next/swc`'s `build` task and:
1. **Skips in CI** — exits immediately when the `CI` env var is set, since CI uses prebuilt `@next/swc-*` npm packages
2. **Finds the last version bump** — uses `git log -G` to locate the commit that last changed `"version":` in `packages/next/package.json`
3. **Checks for Rust changes** — compares `*.rs` files against the working tree (committed + staged + unstaged) since that version bump commit
4. **Rebuilds if needed** — runs `build-native` and copies/formats the generated TypeScript definitions
5. **Clears stale binaries** — if no Rust changes are detected, removes any leftover `.node` files from `native/` so the prebuilt npm packages are used instead
Turborepo's `turbo.json` is configured with Rust-specific inputs (`crates/`, `Cargo.*`, `rust-toolchain`) and `CI` in `env` so CI and local builds get separate cache keys.
### Files changed
- `packages/next-swc/maybe-build-native.mjs` — new script with the conditional build logic
- `packages/next-swc/package.json` — added `"build": "node maybe-build-native.mjs"`
- `packages/next-swc/turbo.json` — added `build` task with Rust inputs, `CI` env, and `native/*.node` outputs
## Summary
- **Agent skills**: 9 new skill files in `.agents/skills/` covering DCE,
flags, react-vendoring, runtime-debug, PR triage, and skill authoring
- **PR status tooling**: `scripts/pr-status.js` script and
`.claude/commands/pr-status.md` command
- **AGENTS.md**: updated with skill references and development
guidelines
## Test plan
- [ ] No runtime behavior changes
- [ ] Docs and tooling only
---------
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
When running `next build --debug-prerender`, React owner stacks are now
captured and displayed in prerender error output. This makes it much
easier to diagnose which component triggered uncached I/O or accessed
request data without Suspense. Previously, `--debug-prerender` only
enabled source maps and disabled minification. Now it also auto-enables
`allowDevelopmentBuild` and sets `NODE_ENV=development`, which loads
React development builds where `captureOwnerStack()` is available.
The main challenge is that with `NODE_ENV=development`, both server and
client bundles include dev-only code paths (HMR, WebSocket connections,
dev overlay, debug channel, etc.) that expect a running dev server. We
don't want these when using `next start`. To solve this, we introduce
`process.env.__NEXT_DEV_SERVER`, an internal env var that is truthy only
during `next dev`. In client bundles, it's inlined at build time (`'1'`
for `next dev`, `''` for `next build`). In production server runtime
bundles, it's inlined as `''` for dead-code elimination. In development
server runtime bundles, it's left as a runtime check because those
bundles are shared between `next dev` (where it's set) and `next build
--debug-prerender` (where it's not). Meanwhile, `NODE_ENV` continues to
control React's dev/prod mode and error formatting, which is exactly
what we want for `--debug-prerender`.
This also replaces the previous `renderOpts.dev` / `workStore.dev`
pattern, which was unreliable because `RouteModule.isDev` was derived
from `NODE_ENV` at compile time. When `allowDevelopmentBuild` set
`NODE_ENV=development`, `isDev` would be compiled as `true` and
incorrectly activate all dev guards during `next start`.
Key changes:
- `config.ts` auto-enables `allowDevelopmentBuild` and sets
`NODE_ENV=development` when `--debug-prerender` is active
- `define-env.ts` inlines `__NEXT_DEV_SERVER` into all bundles (truthy
for dev, falsy for build) so dev-server features are dead-code
eliminated in production and `--debug-prerender` builds
- `next-dev.ts` and `next.ts` set `__NEXT_DEV_SERVER` in the process
environment for externalized server-side code
- `renderOpts.dev` and `workStore.dev` are removed — all consumers now
use `__NEXT_DEV_SERVER` (for dev-server features) or `NODE_ENV` (for
error formatting that should work in both dev and `--debug-prerender`
builds)
- `patch-error-inspect.ts` devirtualizes React server URLs in source map
URLs so they display as readable file paths
This change moves runtime code that does not use a module system and is concatenated by Rust into a dedicated `runtime/` directory so it's not confused with other code.
It also codifies this in a README and instructs agents to read nearby READMEs so they enforce this convention.
**This change only moves code and does not refactor any further.** Snapshot updates reflect the new file paths in the generated runtime code.
**Test Plan:** CI, existing tests
## What?
Added a new section "Task Decomposition and Verification" to AGENTS.md
that provides guidance on breaking down work into smaller, verifiable
tasks and establishing verification practices before moving to the next
step.
## Why?
This guidance helps ensure that AI agents (and developers) work
systematically by:
- Breaking complex goals into incremental, independently verifiable
steps
- Establishing clear verification checkpoints before proceeding
- Choosing appropriate verification methods for different types of
changes
- Asking for clarification when verification approaches are unclear
This promotes more reliable and traceable development practices.
## How?
Added four bullet points under a new "Task Decomposition and
Verification" section that outline:
1. How to split work into smaller, verifiable tasks upfront
2. The importance of verifying each task before moving forward
3. Guidance on selecting appropriate verification methods (tests, type
checking, linting, builds, etc.)
4. When and how to ask users for clarification on verification
approaches
https://claude.ai/code/session_012eJNxH5NRUHKdAaNpz4Yr6
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
Fixes#88316
Route handlers (API routes) were generating bloated
`client-reference-manifest.js` files containing unrelated client
components from pages when using Webpack. This was caused by the
manifest merging logic in `flight-manifest-plugin.ts` which inherited
manifests from all parent path segments.
### Changes
- Modified `flight-manifest-plugin.ts` to detect route handlers
(`/route$` pattern)
- Route handlers now only get their own group's manifest, skipping
parent manifest inheritance
- Pages continue to inherit manifests from parent layouts as before
### Why this works
Route handlers:
- Don't render React components
- Return `Response` objects, not JSX
- Don't need client component references from parent layouts/pages
Turbopack already handles this correctly by doing targeted module graph
traversal per entry. This fix aligns Webpack's behavior.
## Test Plan
Added test suite `test/production/app-dir/route-handler-manifest-size/`:
- Verifies pure route handlers don't include unrelated page client
components
- Verifies pages still include their client components
- Verifies route handlers with direct client imports don't get page
components
- Tests pass for both Webpack and Turbopack
## Summary
Adds a note to AGENTS.md reminding AI agents to carefully count line
numbers when adding `highlight={...}` attributes to documentation code
blocks.
### Changes
- Added "Documentation Code Blocks" subsection under Development
Anti-Patterns in AGENTS.md
- Documents the importance of accounting for empty lines, imports, and
type imports when specifying highlight line numbers
## What?
Updates the AGENTS.md documentation with two clarifications for AI
agents working on the codebase.
## Why?
To improve the quality and consistency of AI-generated contributions by:
1. Ensuring PRs follow the repository's standard description format
2. Making it clear that test generation should use the provided tooling
## How?
Two documentation updates:
1. **PR Template Reference**: Added clarification that PR descriptions
must follow the mandatory format from `.github/pull_request_template.md`
2. **Test Generation Requirement**: Added explicit note that generating
tests using `pnpm new-test` is mandatory, making this requirement more
prominent in the documentation.
---------
Co-authored-by: Niklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
### What?
Adds documentation to AGENTS.md explaining how to create PRs with
descriptions when using Graphite.
### Why?
`gt submit --no-edit` creates PRs in draft mode without a description,
but all PRs require a description following the mandatory format. This
documents the recommended workflow for AI agents.
### How?
Added a new "Creating PRs with descriptions" section to the Git Workflow
documentation with example bash commands showing how to use `gh pr edit`
immediately after `gt submit --no-edit` to add PR descriptions.
## Enhance test documentation with best practices and non-interactive
test generation
### What?
Expanded the AGENTS.md documentation with detailed guidance on writing
tests, including:
- Added non-interactive test generation instructions for AI agents
- Documented best practices for writing tests with code examples
- Provided clear guidance on using `retry()` instead of deprecated
`check()` or `setTimeout`
- Added recommendations for using fixture directories over inline file
definitions
Andrew Clark