Flags

When you're working on Next.js internals and need to add or modify feature flags, this walks you through the required wiring across multiple config files. You'll touch config-shared.ts for types, config-schema.ts for validation, and potentially define-env.ts depending on where the flag gets consumed. The skill breaks down the distinction between client-bundled code (where build-time injection works) and pre-compiled runtime bundles (where you need actual process.env variables set). The documentation is thorough on the two approaches for runtime flags, including the tradeoff between simpler runtime env vars versus separate bundle variants that eliminate dead code but add build complexity. This is narrow and deep, aimed squarely at Next.js contributors rather than app developers.

skills.sh installs: 900
GitHub stars: 139.5K
last updated: May 16, 2026

View on GitHub

Install

$ npx -y skills add vercel/next.js --skill flags --agent claude-code

Installs into .claude/skills of the current project.

Files

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:

SKILL.md on GitHub