flags

vercel/next.js · Agent Skill

Gestisce i flag delle funzionalità sperimentali di Next.js, inclusi aggiunta, modifica e integrazione nel codice.

Vai all'installazione ↓

Opzioni di installazione

Il prompt con anteprima è selezionato di default. Puoi passare al comando diretto.

Installa con Claude o Codex

Copia il prompt, incollalo in Claude, Codex o un altro assistente: analizzerà la pagina dello skill e lo installerà.

I'd like to install this Claude Code skill:
https://github.com/vercel/next.js/tree/canary/.agents/skills/flags

Please review the SKILL.md file, verify the skill is legitimate, then copy the skill folder into .claude/skills/ of my project.

File dello skill

1 file Scarica ZIP

Leggi SKILL.md e i file correlati prima di installare. Clicca un file per l'anteprima.

Contenuto di SKILL.md

Testo originale dell'autore · sola lettura

Feature Flags

Use this skill when adding or changing framework feature flags in Next.js internals.

Required Wiring

All flags need: config-shared.ts (type) → config-schema.ts (zod). If the flag is consumed in user-bundled code (client components, edge routes, app-page.ts template), also add it to define-env.ts for build-time injection. Runtime-only flags consumed exclusively in pre-compiled bundles can skip define-env.ts.

Where the Flag Is Consumed

Client/bundled code only (e.g. __NEXT_PPR in client components): define-env.ts is sufficient. Webpack/Turbopack replaces process.env.X at the user's build time.

Pre-compiled runtime bundles (e.g. code in app-render.tsx): The flag must also be set as a real process.env var at runtime, because app-render.tsx runs from pre-compiled bundles where define-env.ts doesn't reach. Two approaches:

  • Runtime env var: Set in next-server.ts + export/worker.ts. Both code paths stay in one bundle. Simple but increases bundle size.
  • Separate bundle variant: Add DefinePlugin entry in next-runtime.webpack-config.js (scoped to bundleType === 'app'), new taskfile tasks, update module.compiled.js selector, and still set env var in next-server.ts + export/worker.ts for bundle selection. Eliminates dead code but adds build complexity.

For runtime flags, also add the field to the NextConfigRuntime Pick type in config-shared.ts.

Runtime-Bundle Model

  • Runtime bundles are built by next-runtime.webpack-config.js (rspack) via taskfile.js bundle tasks.
  • Bundle selection occurs at runtime in src/server/route-modules/app-page/module.compiled.js based on process.env vars.
  • Variants: {turbo/webpack} × {experimental/stable/nodestreams/experimental-nodestreams} × {dev/prod} = up to 16 bundles per route type.
  • define-env.ts affects user bundling, not pre-compiled runtime internals.
  • process.env.X checks in app-render.tsx are either replaced by DefinePlugin at runtime-bundle-build time, or read as actual env vars at server startup. They are NOT affected by the user's defines from define-env.ts.
  • Gotcha: DefinePlugin entries in next-runtime.webpack-config.js must be scoped to the correct bundleType (e.g. app only, not server) to avoid replacing assignment targets in next-server.ts.

Related Skills

  • $dce-edge - DCE-safe require patterns and edge constraints
  • $react-vendoring - entry-base boundaries and vendored React
  • $runtime-debug - reproduction and verification workflow