1. 26 Jan, 2026 18 commits
    • nextjs-bot's avatar
      v16.2.0-canary.9 · c7d45bb5
      nextjs-bot authored
      c7d45bb5
    • Hendrik Liebau's avatar
    • Tim Neutkens's avatar
      fix: ensure LRU cache items have minimum size of 1 to prevent unbounded growth (#89040) · 9e5759de
      Tim Neutkens authored
      ### What?
      
      Prevent LRU cache unbounded growth by requiring `calculateSize` to
      return values > 0.
      
      ### Why?
      
      When `calculateSize` returned 0 (e.g., for `null` values in the
      filesystem route cache), items were never evicted because they didn't
      contribute to `totalSize`. This caused unbounded memory growth when
      handling dynamic routes like `/api/logs/[id]` where each unique ID
      created a new cache entry with size 0.
      
      ### How?
      
      1. **LRUCache now throws an error if size ≤ 0** - This catches bugs at
      development time rather than silently masking them:
         ```typescript
         if (size <= 0) {
           throw new Error(
      \`LRUCache: calculateSize returned ${size}, but size must be > 0. \` +
      \`Items with size 0 would never be evicted, causing unbounded cache
      growth.\`
           )
         }
         ```
      
      2. **Fixed filesystem.ts** - Null entries (negative cache) now return
      size 1 instead of 0:
         ```typescript
         if (!value) {
      // Null entries (negative cache) still need a non-zero size for LRU
      eviction
           return 1
         }
         ```
      
      3. **Fixed next-dev-server.ts** - Static paths cache now uses `|| 1`
      instead of `?? 0`:
         ```typescript
         return JSON.stringify(value.staticPaths)?.length || 1
         ```
      9e5759de
    • Luke Sandberg's avatar
      Reapply "[turbopack] Add bundling support for worker_threads" (#88725) (#88967) · b690af09
      Luke Sandberg authored
      ## What?
      
      This PR reapplies #87746 which adds bundling support for Node.js `worker_threads` in Turbopack.
      
      ## Why?
      
      The original PR (#87746) was reverted in #88725 because it broke builds that use packages like `pino` with transports. These packages use dynamic patterns like `join(__dirname, 'lib', 'worker.js')` to resolve worker entry points, which can match non-evaluatable files like `package.json` or `tsconfig.json`.
      
      ## How?
      
      This PR reapplies the original changes with the following fixes:
      
      1. **Downgrade errors to warnings in tracing contexts**: When `loose_errors` is enabled (tracing mode) or `in_try` is true, worker entry point validation errors are now emitted as warnings instead of errors. This follows the established Turbopack pattern used in `handle_resolve_error` and other resolve error handling.
      
      2. **Improved error messages**: Error messages for non-chunkable and non-evaluatable worker entry point modules now include:
         - The module identifier (so you can see which file caused the issue)
         - The issue source location (pointing to the `new Worker()` call in source code)
      
      3. **Added regression test**: A new pino-based test case exercises the `thread-stream` worker pattern that caused the original failure. This test runs in `CodeGenerationAndTracing` mode via `test-start-turbo`.
      
      ## Changes from original PR
      
      - Added `source` field to `CodeGenerationIssue` to support showing issue source locations
      - Added `get_issue_severity()` helper that checks `loose_errors` and `in_try` to determine severity
      - Fixed typo: `"SharedbWorker"` → `"SharedWorker"` in `to_string` implementation
      - Added pino regression test in `test/e2e/app-dir/node-worker-threads/`
      
      ## Testing
      
      - ✅ `pnpm test-dev-turbo test/e2e/app-dir/node-worker-threads/` - all tests pass
      - ✅ `pnpm test-start-turbo test/e2e/app-dir/node-worker-threads/` - all tests pass (exercises bundling mode)
      - ✅ Verified test fails without the `loose_errors` fix
      - ✅ Verified vercel-docs build succeeds with warnings instead of errors
      b690af09
    • Jiachi Liu's avatar
      bb88ea52
    • Delba de Oliveira's avatar
      Cache Component Guide: Building public, _mostly_ static pages (#87248) · d1cf4e69
      Delba de Oliveira authored
      This PR adds a draft guide for building public pages with Cache
      Components and PPR.
      
      Part of a 3-guide series on:
      
      - Building public pages with shared data
      - Building page variants with route params (`generateStaticParams`)
      - Build private pages with user-specific data
      
      Todo: 
      
      - [x] Link to glossary terms
      - [x] Link to video
      - [x] Link to demo + code
      d1cf4e69
    • Niklas Mischkulnig's avatar
      Fix chunk loading when using `__turbopack_load_by_url__` with query (#88899) · b3f77636
      Niklas Mischkulnig authored
      - if you `await __turbopack_load_by_url__ `, it waits for the exact chunk url you passed in to load
      - but when that chunk actually loads, it registers itself with `stripQuery(chunkurl)+CHUNK_SUFFIX`
      
      so there was mismatch if you load a chunk from a different deployment and thus `await __turbopack_load_by_url__` never resolves
      
      
      
      ----
      
      Very confused about what's going on here:
      
      ```
       FAIL   Turbopack  test/e2e/app-dir/segment-cache/deployment-skew/deployment-skew.test.ts (61.629 s)
        segment cache (deployment skew)
          with BUILD_ID
            ✓ does not crash when prefetching a dynamic, non-PPR page on a different deployment (11673 ms)
            ✓ does not crash when prefetching a static page on a different deployment (10744 ms)
          with NEXT_DEPLOYMENT_ID
            ✓ does not crash when prefetching a dynamic, non-PPR page on a different deployment (10924 ms)
            ✕ does not crash when prefetching a static page on a different deployment (15756 ms)
      
        ● segment cache (deployment skew) › with NEXT_DEPLOYMENT_ID › does not crash when prefetching a static page on a different deployment
      
          page.waitForSelector: Timeout 5000ms exceeded.
          Call log:
            - waiting for locator('#build-id') to be visible
      
            519 |
            520 |     return this.startChain(async () => {
          > 521 |       const el = await page.waitForSelector(selector, {
                |                             ^
            522 |         timeout,
            523 |         state,
            524 |       })
      
            at waitForSelector (lib/browsers/playwright.ts:521:29)
            at Playwright._chain (lib/browsers/playwright.ts:651:23)
            at Playwright._chain [as startChain] (lib/browsers/playwright.ts:632:17)
            at Playwright.startChain [as waitForElementByCss] (lib/browsers/playwright.ts:520:17)
            at Playwright.waitForElementByCss [as elementByCss] (lib/browsers/playwright.ts:405:17)
            at Playwright.elementByCss [as elementById] (lib/browsers/playwright.ts:425:17)
            at Object.elementById (e2e/app-dir/segment-cache/deployment-skew/deployment-skew.test.ts:122:37)
      
      ```
      
      In the browser debugger, this line here in `fetchServerResponse` never returns, so there is actually no navigation at all (neither SPA nor MPA) when clicking the link, should be doing an MPA nav
      
      https://github.com/vercel/next.js/blob/d4e64f52bb9aeb5dbcf6bb484f204742b2e3d743/packages/next/src/client/components/router-reducer/fetch-server-response.ts#L242
      b3f77636
    • Jiachi Liu's avatar
      cb1dbfb8
    • Luke Sandberg's avatar
      Fix react-loadable-manifest chunk hash mismatch by preserving async loader mapping (#88775) · e78d35b3
      Luke Sandberg authored
      ## What?
      
      Fixes a bug where `react-loadable-manifest.json` in Turbopack dev mode
      contained references to chunk files with wrong hashes, causing 404
      errors when loading dynamic imports.
      
      ## Why?
      
      When using `next/dynamic` with nested imports (e.g., a dynamic component
      that itself imports other modules), the chunk files referenced in
      `react-loadable-manifest.json` had different hashes than the actual
      generated chunk files.
      
      The root cause was that `collect_next_dynamic_chunks` was
      **recomputing** chunk content that was already computed by
      `make_chunk_group`. This pattern was inherently brittle because Next.js
      code had to carefully mirror Turbopack's internal chunking logic to get
      consistent hashes.
      
      This brittleness was exposed when the
      `turbopackClientSideNestedAsyncChunking` feature was disabled in dev
      mode (released in 16.1). The subtle differences in how availability info
      was computed led to hash mismatches.
      
      ## How?
      
      Instead of recomputing chunks for next/dynamic imports, this PR
      preserves the module→async loader mapping from when chunks are first
      computed in `make_chunk_group`, and looks up pre-computed chunks
      directly. This eliminates the need for Next.js to replicate Turbopack's
      chunking logic.
      
      ### Key changes:
      
      1. **Extended `MakeChunkGroupResult` and `ChunkGroupResult`** with
      `async_loaders_by_module` field
      - Maps `ResolvedVc<Box<dyn ChunkableModule>>` → `ResolvedVc<Box<dyn
      ChunkItem>>`
         - Preserves the module→loader relationship computed during chunking
      
      2. **Eliminated redundancy** in `MakeChunkGroupResult`
      - Removed the separate `references` field (was just upcasted async
      loaders)
      - Added `references()` method that derives references on-demand from the
      map
      
      3. **Simplified `collect_next_dynamic_chunks`**
         - Now performs simple lookup instead of recomputation
         - Removed `module_graph` and `chunking_context` parameters
      - Uses `NextDynamicChunkAvailability` enum to access pre-computed chunk
      groups
      
      4. **Added regression test** to verify chunk files referenced in
      manifest exist
      
      ### Files modified:
      - `turbopack/crates/turbopack-core/src/chunk/chunk_group.rs` - Add
      mapping, remove redundant field
      - `turbopack/crates/turbopack-core/src/chunk/chunking_context.rs` -
      Extend ChunkGroupResult
      - `turbopack/crates/turbopack-browser/src/chunking_context.rs` - Pass
      through mapping
      - `turbopack/crates/turbopack-nodejs/src/chunking_context.rs` - Pass
      through mapping
      - `crates/next-api/src/dynamic_imports.rs` - Lookup instead of recompute
      - `crates/next-api/src/pages.rs` - Updated caller
      - `crates/next-api/src/app.rs` - Updated caller
      - `crates/next-core/src/next_app/app_client_references_chunks.rs` -
      Initialize empty map
      
      Fixes #87680
      e78d35b3
    • msmx-mnakagawa's avatar
      docs: fix typos in `README.md`s (#89022) · cabe5458
      msmx-mnakagawa authored
      <!-- 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 #
      
      -->
      
      > [!NOTE]
      > This PR only includes documentation updates and has no impact on
      runtime behavior.
      
      ### What?
      
      Just fixed typos in docs.
      
      ### How?
      
      - `direcly` → `directly`
      - `existance` → `existence`
      - `overriden` → `overridden`
      cabe5458
    • Niklas Mischkulnig's avatar
      [test] Improve deployment skew test for Pages Router data routes (#89038) · b9ee1db2
      Niklas Mischkulnig authored
      Actually test the behavior by switching between two builds, as opposed
      to selectively blocking some routes.
      b9ee1db2
    • Joseph's avatar
    • Joseph's avatar
      docs: improve clarity in cache components and server/client docs (#88946) · 0a6b9ba5
      Joseph authored
      - Applying learnings from a recipe
      - React.cache usage under a use cache scope
      0a6b9ba5
    • Tobias Koppers's avatar
      a57e4e80
    • Niklas Mischkulnig's avatar
      Rename `renderOpts.nextExport` to `isBuildTimePrerendering` (#88951) · c26b4a68
      Niklas Mischkulnig authored
      Rename to reflect what this property actually means
      c26b4a68
    • Vercel Release Bot's avatar
      Update Rspack production test manifest (#89003) · 9ebd3358
      Vercel Release Bot authored
      This auto-generated PR updates the production integration test manifest used when testing Rspack.
      9ebd3358
    • Vercel Release Bot's avatar
      Update Rspack development test manifest (#89004) · 905e9050
      Vercel Release Bot authored
      This auto-generated PR updates the development integration test manifest used when testing Rspack.
      905e9050
    • JJ Kasper's avatar
      Apply fixes for onBuildComplete and route module (#88831) · 93bb2799
      JJ Kasper authored
      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: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
      93bb2799
  2. 25 Jan, 2026 4 commits
    • nextjs-bot's avatar
      v16.2.0-canary.8 · f4c2d546
      nextjs-bot authored
      f4c2d546
    • Kim Dong Gyu's avatar
      [Reapply] Add `useEffectEvent` to disallowed React APIs in Server Components (#88985) · 7eb2ea49
      Kim Dong Gyu authored
      <!-- 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 #
      
      -->
      ### What?
      Add `useEffectEvent` to the list of invalid React APIs in Server
      Components.
      
      ### Why?
      Using `useEffectEvent` in a Server Component results in a **runtime
      error**: TypeError: (0 , react_1.useEffectEvent) is not a function.
      Without this fix, developers only discover the mistake at runtime. This
      change improves the **Developer Experience (DX) by catching the error
      immediately in the IDE.**
      
      #### Expected Behavior
      <img width="999" height="566" alt="image"
      src="https://github.com/user-attachments/assets/79c1cbf9-ae0e-4ad7-b163-f650fb289a3a"
      />
      
      #### Currently
      <img width="1708" height="805" alt="image"
      src="https://github.com/user-attachments/assets/a33f73e5-24fd-4405-826a-53f1810154a7"
      />
      <img width="2091" height="812" alt="image"
      src="https://github.com/user-attachments/assets/ed3f191e-a34d-42dd-8779-1d524f6f035d"
      />
      
      ### How?
      - Added `useEffectEvent` to Rust RSC transform
      (`react_server_components.rs`)
      - Added `useEffectEvent` to TypeScript constants (`constant.ts`)
      - Added `useEffectEvent` to error formatting (`format-server-error.ts`)
      - Added test fixture and updated test file
      
      ## Note
      
      This is a reapply of the previous
      [PR](https://github.com/vercel/next.js/pull/88950).
      With help from @timneutkens, I all previously worked code to ensure
      nothing was missed before resubmitting.
      Co-authored-by: 's avatarTim Neutkens <tim@timneutkens.nl>
      7eb2ea49
    • Luke Sandberg's avatar
      [Turbopack] Use a presized scratch buffer for task encoding (#88924) · 1637d617
      Luke Sandberg authored
      ### What
      
      Pass a shared buffer to use as scratch space for encoding TaskStorage values.
      
      Also reduce the size of the `CollectorEntryValue` enum (32->24 bytes), our use of a `SmallVec` was inefficient, instead we can store more inline data by doing it ourselves (22 bytes instead of 16)
      
      ### Why
      
      Currently whenever we encode `TaskStorage` we allocate a new `TurboBincodeBuffer` (aka `SmallVec<[u8;16>`) only the very smallest TaskStorage values fit in that space, so we are always allocating and resizing a buffer for every `TaskStorage` we encode.   Using a shared scratch buffer we avoid resizes and allocations during encoding but now always need to copy our data out of the shared buffer.
      
      This should reduce temporary allocations and buffer copies from the resizes in the common case. As well as ensure that the buffers we pass through to the collectors are exactly sized
      
      I presized it as 4096 bytes since this covers ~98% of tasks we encode, and it is a nice magic number
      
      
      A future optimization could be to accumulate all writes for every SnapshotShard in a single buffer that we pass down to the `Collector`.
      1637d617
    • Jude Gao's avatar
      Improve agents-md prompt to force doc retrieval (#88997) · 39ce0124
      Jude Gao authored
      ## Summary
      
      Updates the instruction in `agents-md` [CLAUDE.md](http://CLAUDE.md)
      output to force LLMs to actually read the docs instead of relying on
      stale pre-training knowledge.
      
      **Before:**
      
      ```
      IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
      ```
      
      **After:**
      
      ```
      STOP. What you remember about Next.js is WRONG for this project. Always search docs and read before any task.
      ```
      
      ## Why This Matters
      
      Through systematic testing with the
      [next-evals-oss](https://github.com/vercel/next-evals-oss) eval suite,
      we discovered that the original "prefer retrieval-led reasoning"
      instruction was ineffective. Agents would ignore it and use outdated
      pre-training knowledge (e.g., creating `middleware.ts` instead of the
      new Next.js 16 `proxy.ts` convention).
      
      ## Testing Methodology
      
      We created an "indirect proxy" eval that tests if agents know `proxy.ts`
      is needed for request interception in Next.js 16+, using only the prompt
      "Log every request to the console" (no mention of proxy/middleware).
      
      | Instruction | Pass Rate |
      | --- | --- |
      | "Prefer retrieval-led reasoning" | 0% |
      | "CRITICAL: MUST read docs" | ~20-40% |
      | "What you remember is WRONG" | **100% (6/6)** |
      
      ## Why It Works
      
      The phrase **"What you remember is WRONG"** creates psychological doubt
      in the model's confidence, forcing it to actually read the docs rather
      than trusting its pre-training.
      
      Key elements:
      
      - **"STOP"** - Attention grabber, interrupts default behavior
      - **"WRONG for this project"** - Creates doubt without claiming
      universal wrongness
      - **"Always search docs and read"** - Actionable instruction
      - **"before any task"** - Applies to everything, not just code writing
      
      ## Full Suite Results
      
      - The new indirect-proxy eval passed consistently
      39ce0124
  3. 24 Jan, 2026 4 commits
    • nextjs-bot's avatar
      v16.2.0-canary.7 · f51e3acf
      nextjs-bot authored
      f51e3acf
    • Hanzala Sohrab's avatar
      docs: Update Partytown URLs and package reference (#88928) · d8a0f6ca
      Hanzala Sohrab authored
      - Update Partytown documentation links from `builder.io` to `qwik.dev`.
      - Update Partytown installation package reference in the guide.
      
      <!-- 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
      
      - [x] Run `pnpm prettier-fix` to fix formatting issues before opening
      the PR.
      - [x] 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?
      Updated Partytown documentation URLs and the installation package
      reference in the `next/script` guide.
      
      ### Why?
      Partytown documentation and packages have moved from `builder.io` to
      `qwik.dev`. The old links were outdated, and the package reference
      needed to be updated to `@qwik.dev/partytown` to ensure users install
      the correct version.
      
      ### How?
      Updated
      [docs/01-app/02-guides/scripts.mdx](cci:7://file:///home/hanzala/Projects/personal/next.js/docs/01-app/02-guides/scripts.mdx:0:0-0:0)
      to replace `partytown.builder.io` with `partytown.qwik.dev` and updated
      the `npm install` instruction.
      
      Closes NEXT-
      Fixes #
      d8a0f6ca
    • Vercel Release Bot's avatar
      Update font data (#88975) · 89cddc26
      Vercel Release Bot authored
      This auto-generated PR updates font data with latest available
      Co-authored-by: 's avatarnextjs-bot <it+nextjs-bot@vercel.com>
      89cddc26
    • Jude Gao's avatar
      feat(next-codemod): add agents-md command for AI coding agents (#88961) · 1e859c06
      Jude Gao authored
      ## Summary
      
      Adds a new `agents-md` subcommand to `@next/codemod` that generates a
      Next.js documentation index for AI coding agents (Claude, Cursor, GitHub
      Copilot, etc.).
      
      ## Usage
      
      ```bash
      # Interactive mode - prompts for version and target file
      npx @next/codemod agents-md
      
      # Non-interactive mode
      npx @next/codemod agents-md --version 15.1.0 --output CLAUDE.md
      
      # Auto-detect version, specify output
      npx @next/codemod agents-md --output AGENTS.md
      ```
      
      ## What it does
      
      1. Downloads the Next.js documentation matching your project's version
      to `.next-docs/` (via git sparse-checkout)
      2. Generates a compact index of all doc files grouped by directory
      3. Injects the index into `CLAUDE.md` or `AGENTS.md` between marker
      comments
      4. Adds `.next-docs/` to `.gitignore`
      
      The index helps AI agents prefer local documentation over pre-trained
      knowledge, ensuring answers match your Next.js version.
      
      ## Options
      
      | Option | Description |
      |--------|-------------|
      | `--version <version>` | Specify Next.js version (auto-detected from
      `package.json` if not provided) |
      | `--output <file>` | Target file path (e.g., `CLAUDE.md`, `AGENTS.md`)
      |
      
      ## Output format
      
      The generated index is a single line with pipe separators:
      
      ```
      <!-- NEXT-AGENTS-MD-START -->[Next.js Docs Index]|root: ./.next-docs|IMPORTANT: Prefer retrieval-led reasoning...|dir:{file1.mdx,file2.mdx}|...<!-- NEXT-AGENTS-MD-END -->
      ```
      
      ## Test plan
      
      - [x] Build passes
      - [x] Tested interactive mode
      - [x] Tested non-interactive mode with `--version` and `--output`
      - [x] Tested auto-detect version with `--output` only
      - [x] Verified `.gitignore` is updated
      - [x] Verified index is injected correctly (new file and existing file)
      
      ## Eval results
      
      Tested against 19 Next.js-specific agent evals with 100% pass rate:
      
      | Eval | Result |
      |------|--------|
      | agent-000-app-router-migration-simple | ✅✅✅ (89.5s) |
      | agent-021-avoid-fetch-in-effect | ✅✅✅ (90.4s) |
      | agent-022-prefer-server-actions | ✅✅✅ (67.1s) |
      | agent-023-avoid-getserversideprops | ✅✅✅ (102.5s) |
      | agent-024-avoid-redundant-usestate | ✅✅✅ (62.9s) |
      | agent-025-prefer-next-link | ✅✅✅ (69.5s) |
      | agent-026-no-serial-await | ✅✅✅ (96.2s) |
      | agent-027-prefer-next-image | ✅✅✅ (68.0s) |
      | agent-028-prefer-next-font | ✅✅✅ (64.2s) |
      | agent-029-use-cache-directive | ✅✅✅ (76.6s) |
      | agent-030-app-router-migration-hard | ✅✅✅ (220.8s) |
      | agent-031-proxy-middleware | ✅✅✅ (92.4s) |
      | agent-032-use-cache-directive | ✅✅✅ (71.3s) |
      | agent-033-forbidden-auth | ✅✅✅ (100.6s) |
      | agent-034-async-cookies | ✅✅✅ (68.7s) |
      | agent-035-connection-dynamic | ✅✅✅ (65.2s) |
      | agent-036-after-response | ✅✅✅ (68.7s) |
      | agent-037-updatetag-cache | ✅✅✅ (70.3s) |
      | agent-038-refresh-settings | ✅✅✅ (71.8s) |
      | **Overall** | **19/19/19 (100%, 100%, 100%)** |
      
      Legend: ✅✅✅ = Build/Lint/Test
      1e859c06
  4. 23 Jan, 2026 14 commits