flags

vercel/next.js · Agent Skill

Manages experimental Next.js feature flags, including adding, modifying, and integrating them into code.

Jump to install ↓

Install options

The review-first prompt is selected by default. You can switch to a direct command.

Install with Claude or Codex

Copy the prompt, paste it into Claude, Codex, or another assistant, and it will review the skill page and install it.

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.

Review the source files

1 files Download Zip

Read SKILL.md and any companion files before deciding whether to install. Click a file to preview it.

SKILL.md contents

Original author text · read-only

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