[pull] canary from vercel:canary

.agents/skills/write-api-reference/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: write-api-reference
+description: |
+  Produces API reference documentation for Next.js APIs: functions, components, file conventions, directives, and config options.
+
+  **Auto-activation:** User asks to write, create, or draft an API reference page. Also triggers on paths like `docs/01-app/03-api-reference/`, or keywords like "API reference", "props", "parameters", "returns", "signature".
+
+  **Input sources:** Next.js source code, existing API reference pages, or user-provided specifications.
+
+  **Output type:** A markdown (.mdx) API reference page with YAML frontmatter, usage example, reference section, behavior notes, and examples.
+agent: Plan
+context: fork
+---
+
+# Writing API Reference Pages
+
+## Goal
+
+Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven.
+
+Each page documents **one API**. If the API has sub-methods (like `cookies.set()`), document them on the same page. If two APIs are independent, they get separate pages.
+
+## Structure
+
+Identify which category the API belongs to, then follow the corresponding template.
+
+### Categories
+
+1. **Function** (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples
+2. **Component** (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples
+3. **File convention** (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples
+4. **Directive** (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference
+5. **Config option** (`basePath`, `images`, etc.): definition, config code, behavioral sections
+
+### Template
+
+````markdown
+---
+title: {API name}
+description: {API Reference for the {API name} {function|component|file convention|directive|config option}.}
+---
+
+{One sentence defining what it does and where it's used.}
+
+```tsx filename="path/to/file.tsx" switcher
+// Minimal working usage
+```
+
+```jsx filename="path/to/file.js" switcher
+// Same example in JS
+```
+
+## Reference
+
+{For functions: methods/params table, return type.}
+{For components: props summary table, then `#### propName` subsections.}
+{For file conventions: `### Props` with `#### propName` subsections.}
+{For directives: usage rules and serialization constraints.}
+{For config: options table or individual option docs.}
+
+### {Subsection name}
+
+{Description + code example + table of values where applicable.}
+
+## Good to know
+
+- {Default behavior or implicit effects.}
+- {Caveats, limitations, or version-specific notes.}
+- {Edge cases the developer should be aware of.}
+
+## Examples
+
+### {Example name}
+
+{Brief context, 1-2 sentences.}
+
+```tsx filename="path/to/file.tsx" switcher
+// Complete working example
+```
+
+```jsx filename="path/to/file.js" switcher
+// Same example in JS
+```
+
+## Version History
+
+| Version  | Changes         |
+| -------- | --------------- |
+| `vX.Y.Z` | {What changed.} |
+````
+
+**Category-specific notes:**
+
+- **Functions**: Lead with the function signature and `await` if async. Document methods in a table if the return value has methods (like `cookies`). Document options in a separate table if applicable.
+- **Components**: Start with a props summary table (`| Prop | Example | Type | Required |`). Then document each prop under `#### propName` with description, code example, and value table where useful.
+- **File conventions**: Show the default export signature with TypeScript types. Document each prop (`params`, `searchParams`, etc.) under `#### propName` with a route/URL/value example table.
+- **Directives**: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules.
+- **Config options**: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect.
+
+## Rules
+
+1. **Lead with what it does.** First sentence defines the API. No preamble.
+2. **Show working code immediately.** A minimal usage example appears right after the opening sentence, before `## Reference`.
+3. **Use `switcher` for tsx/jsx pairs.** Always include both. Always include `filename="path/to/file.ext"`.
+4. **Use `highlight={n}` for key lines.** Highlight the line that demonstrates the API being documented.
+5. **Tables for simple APIs, subsections for complex ones.** If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a `####` subsection.
+6. **Behavior section uses `> **Good to know**:`or`## Good to know`.** Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:".
+7. **Examples section uses `### Example Name` subsections.** Each example solves one specific use case.
+8. **Version History table at the end.** Include when the API has changed across versions. Omit for new APIs.
+9. **No em dashes.** Use periods, commas, or parentheses instead.
+10. **Mechanical, observable language.** Describe what happens, not how it feels. "Returns an object" not "gives you an object".
+11. **Link to related docs with relative paths.** Use `/docs/app/...` format.
+12. **No selling or justifying.** No "powerful", "easily", "simply". State what the API does.
+
+| Don't                                                   | Do                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| "This powerful function lets you easily manage cookies" | "`cookies` is an async function that reads HTTP request cookies in Server Components"       |
+| "You can conveniently access..."                        | "Returns an object containing..."                                                           |
+| "The best way to handle navigation"                     | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" |
+
+## Workflow
+
+1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
+2. **Identify the API category** (function, component, file convention, directive, config).
+3. **Research the implementation.** Read the source code to understand params, return types, edge cases, and defaults.
+4. **Check e2e tests.** Search `test/` for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
+5. **Check existing related docs** for linking opportunities and to avoid duplication.
+6. **Write using the appropriate category template.** Follow the rules above.
+7. **Review against the rules.** Verify: one sentence opener, immediate code example, correct `switcher`/`filename` usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language.
+
+## References
+
+Read these pages in `docs/01-app/03-api-reference/` before writing. They demonstrate the patterns above.
+
+- `04-functions/cookies.mdx` - Function with methods table, options table, and behavior notes
+- `03-file-conventions/page.mdx` - File convention with props subsections and route/URL/value tables
+- `02-components/link.mdx` - Component with props summary table and detailed per-prop docs
+- `01-directives/use-client.mdx` - Directive with usage section and serialization rules
+- `04-functions/fetch.mdx` - Function with troubleshooting section and version history

.agents/skills/write-guide/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: write-guide
+description: |
+  Generates technical guides that teach real-world use cases through progressive examples.
+
+  **Auto-activation:** User asks to write, create, or draft a guide or tutorial. Also use when converting feature documentation, API references, or skill knowledge into step-by-step learning content.
+
+  **Input sources:** Feature skills, API documentation, existing code examples, or user-provided specifications.
+
+  **Output type:** A markdown guide with YAML frontmatter, introduction, 2-4 progressive steps, and next steps section.
+agent: Plan
+context: fork
+---
+
+# Writing Guides
+
+## Goal
+
+Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.
+
+Each guide solves **one specific problem**. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.
+
+## Structure
+
+Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.
+
+Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.
+
+Sections: introduction (no heading, 2 paragraphs max), `## Example` (what we're building + source link), `### Step N` (action-oriented titles, 2-4 steps), `## Next steps` (summary + related links).
+
+Headings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.
+
+### Template
+
+````markdown
+---
+title: {Action-oriented, e.g., "Building X" or "How to Y"}
+description: {One sentence}
+nav_title: {Short title for navigation}
+---
+
+{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}
+
+## Example
+
+As an example, we'll build {what we're building}.
+
+We'll start with {step 1}, then {step 2}, and {step 3}.
+
+{Source code link.}
+
+### Step 1: {Action-oriented title}
+
+{Brief context, 1-2 sentences.}
+
+```tsx filename="path/to/file.tsx"
+// Minimal working code
+```
+
+{Explain what happens.}
+
+{Introduce friction: warning, limitation, or constraint.}
+
+{Resolution: explain the choice, apply the fix.}
+
+{Verify the fix with observable proof.}
+
+### Step 2: {Action-oriented title}
+
+{Same pattern: context → code → explain → friction → resolution → proof.}
+
+### Step 3: {Action-oriented title}
+
+{Same pattern.}
+
+## Next steps
+
+You now know how to {summary}.
+
+Next, learn how to:
+
+- [Related guide 1]()
+- [Related guide 2]()
+````
+
+### Workflow
+
+1. **Research**: Check available skills for relevant features. Read existing docs for context and linking opportunities.
+2. **Plan**: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
+3. **Write**: Follow the template above. Apply the rules below.
+4. **Review**: Re-read the rules, verify, then present.
+
+## Rules
+
+1. **Progressive disclosure.** Start with the smallest working example. Introduce complexity only when the example breaks. Name concepts at the moment of resolution, after the reader has felt the problem. Full loop: working → new requirement → something breaks → explain why → name the fix → apply → verify with proof → move on.
+2. **Show problems visually.** Console errors, terminal output, build warnings, slow-loading pages. "If we refresh the page, we can see the component blocks the response."
+3. **Verify resolutions with observable proof.** Before/after comparisons, browser reloads, terminal output. "If we refresh the page again, we can see it loads instantly."
+4. **One friction point per step.** If a step has multiple friction points, split it.
+5. **Minimal code blocks.** Only the code needed for the current step. Collapse unchanged functions with `function Header() {}`.
+6. **No em dashes.** Use periods, commas, or parentheses instead.
+7. **Mechanical, observable language.** Describe what happens, not how it feels.
+8. **No selling, justifying, or comparing.** No "the best way," no historical context, no framework comparisons.
+
+| Don't                                                | Do                                                       |
+| ---------------------------------------------------- | -------------------------------------------------------- |
+| "creates friction in the pipeline"                   | "blocks the response"                                    |
+| "needs dynamic information"                          | "depends on request-time data"                           |
+| "requires dynamic processing"                        | "output can't be known ahead of time"                    |
+| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |
+
+## References
+
+Read these guides in `docs/01-app/02-guides/` before writing. They demonstrate the patterns above.
+
+- `public-static-pages.mdx` — intro → example → 3 progressive steps → next steps. Concepts named at point of resolution. Problems shown with build output.
+- `forms.mdx` — progressive feature building without explicit "Step" labels. Each section adds one capability.

contributing/core/developing.md

@@ -180,17 +180,3 @@ pnpm sweep
 ```
 
 It will also clean up other caches (pnpm store, cargo, etc.) and run `git gc` for you.
-
-### MacOS disk compression
-
-If you want to automatically use APFS disk compression on macOS for `node_modules/` and `target/` you can install a launch agent with:
-
-```bash
-./scripts/LaunchAgents/install-macos-agents.sh
-```
-
-Or run it manually with:
-
-```bash
-./scripts/macos-compress.sh
-```

crates/next-api/src/app.rs

@@ -1358,45 +1358,52 @@ impl AppEndpoint {
 
         let manifest_path_prefix = &app_entry.original_name;
 
-        // polyfill-nomodule.js is a pre-compiled asset distributed as part of next
-        let next_package = get_next_package(project.project_path().owned().await?).await?;
-        let polyfill_source_path =
-            next_package.join("dist/build/polyfills/polyfill-nomodule.js")?;
-        let polyfill_source = FileSource::new(polyfill_source_path.clone());
-        let polyfill_output_path = client_chunking_context
-            .chunk_path(
-                Some(Vc::upcast(polyfill_source)),
-                polyfill_source.ident(),
-                None,
-                rcstr!(".js"),
-            )
-            .owned()
-            .await?;
-
-        let polyfill_output = SingleFileEcmascriptOutput::new(
-            polyfill_output_path.clone(),
-            polyfill_source_path,
-            Vc::upcast(polyfill_source),
-        )
-        .to_resolved()
-        .await?;
-
-        let polyfill_output_asset = ResolvedVc::upcast(polyfill_output);
-        client_assets.insert(polyfill_output_asset);
+        // Only Pages need a polyfill chunk, Routes handlers don't have any inherent code that runs
+        // in the browser.
+        let polyfill_output_asset = if matches!(this.ty, AppEndpointType::Page { .. }) {
+            // polyfill-nomodule.js is a pre-compiled asset distributed as part of next
+            let next_package = get_next_package(project.project_path().owned().await?).await?;
+            let polyfill_source_path =
+                next_package.join("dist/build/polyfills/polyfill-nomodule.js")?;
+            let polyfill_source = FileSource::new(polyfill_source_path.clone());
+            let polyfill_output_path = client_chunking_context
+                .chunk_path(
+                    Some(Vc::upcast(polyfill_source)),
+                    polyfill_source.ident(),
+                    None,
+                    rcstr!(".js"),
+                )
+                .owned()
+                .await?;
 
-        let client_source_maps = project
-            .next_config()
-            .client_source_maps(project.next_mode())
-            .await?;
-        if *client_source_maps != SourceMapsType::None {
-            let polyfill_source_map_asset = SourceMapAsset::new_fixed(
+            let polyfill_output = SingleFileEcmascriptOutput::new(
                 polyfill_output_path.clone(),
-                *ResolvedVc::upcast(polyfill_output),
+                polyfill_source_path,
+                Vc::upcast(polyfill_source),
             )
             .to_resolved()
             .await?;
-            client_assets.insert(ResolvedVc::upcast(polyfill_source_map_asset));
-        }
+
+            let polyfill_output_asset = ResolvedVc::upcast(polyfill_output);
+            client_assets.insert(polyfill_output_asset);
+
+            let client_source_maps = project
+                .next_config()
+                .client_source_maps(project.next_mode())
+                .await?;
+            if *client_source_maps != SourceMapsType::None {
+                let polyfill_source_map_asset = SourceMapAsset::new_fixed(
+                    polyfill_output_path.clone(),
+                    *ResolvedVc::upcast(polyfill_output),
+                )
+                .to_resolved()
+                .await?;
+                client_assets.insert(ResolvedVc::upcast(polyfill_source_map_asset));
+            }
+            Some(polyfill_output_asset)
+        } else {
+            None
+        };
 
         let client_assets: ResolvedVc<OutputAssets> =
             ResolvedVc::cell(client_assets.into_iter().collect::<Vec<_>>());
@@ -1437,7 +1444,7 @@ impl AppEndpoint {
                 client_relative_path: client_relative_path.clone(),
                 pages: Default::default(),
                 root_main_files: client_shared_chunks,
-                polyfill_files: vec![polyfill_output_asset],
+                polyfill_files: polyfill_output_asset.into_iter().collect(),
             };
             server_assets.insert(ResolvedVc::upcast(build_manifest.resolved_cell()));
         }

crates/next-core/src/next_client/context.rs

@@ -11,13 +11,13 @@ use turbopack::module_options::{
     side_effect_free_packages_glob,
 };
 use turbopack_browser::{
-    BrowserChunkingContext, ContentHashing, CurrentChunkMethod,
-    react_refresh::assert_can_resolve_react_refresh,
+    BrowserChunkingContext, CurrentChunkMethod, react_refresh::assert_can_resolve_react_refresh,
 };
 use turbopack_core::{
     chunk::{
-        AssetSuffix, ChunkingConfig, ChunkingContext, MangleType, MinifyType, SourceMapSourceType,
-        SourceMapsType, UnusedReferences, UrlBehavior, chunk_id_strategy::ModuleIdStrategy,
+        AssetSuffix, ChunkingConfig, ChunkingContext, ContentHashing, MangleType, MinifyType,
+        SourceMapSourceType, SourceMapsType, UnusedReferences, UrlBehavior,
+        chunk_id_strategy::ModuleIdStrategy,
     },
     compile_time_info::{CompileTimeDefines, CompileTimeInfo, FreeVarReference, FreeVarReferences},
     environment::{BrowserEnvironment, Environment, ExecutionEnvironment},
@@ -530,7 +530,7 @@ pub async fn get_client_chunking_context(
                     ..Default::default()
                 },
             )
-            .use_content_hashing(ContentHashing::Direct { length: 16 })
+            .chunk_content_hashing(ContentHashing::Direct { length: 13 })
             .module_merging(*scope_hoisting.await?);
     }