flags_skill

Overview

This skill explains how to add or modify Next.js experimental feature flags end-to-end inside the framework. It covers type declaration, zod schema wiring, build-time injection for user bundles, runtime env plumbing for pre-compiled runtime bundles, and the trade-offs between runtime env-var branching and separate bundle variants. Use it when changing files like config-shared.ts, config-schema.ts, define-env-plugin.ts, next-server.ts, export/worker.ts, or module.compiled.js. The guidance targets maintainable, predictable flag behavior across build and runtime surfaces.

How this skill works

Every flag must be declared in config-shared.ts (type) and validated in config-schema.ts (zod). If the flag will be read from user-bundled code (client components, edge routes, app templates), add it to define-env.ts so the bundler injects a build-time replacement. Flags consumed by pre-compiled runtime bundles require actual process.env values at server startup or separate runtime-bundle variants built with DefinePlugin and selected via module.compiled.js.

When to use it

• Adding a new experimental flag exposed to app or client code
• Changing an existing flag used in both user bundles and pre-compiled runtime code
• Deciding whether to eliminate dead code via separate runtime bundle variants
• Wiring a runtime-only flag that must affect server-side precompiled bundles
• Validating flag values and types across config-shared.ts and config-schema.ts

Best practices

• Always add the flag type to config-shared.ts and the zod entry in config-schema.ts
• If user code will import the flag, add it to define-env.ts for build-time injection
• For flags used in pre-compiled runtime code, ensure process.env is set in next-server.ts and export/worker.ts
• Prefer separate bundle variants only when dead-code elimination yields meaningful size savings—accept added build complexity otherwise
• Scope DefinePlugin entries in next-runtime.webpack-config.js to the correct bundleType to avoid accidental replacements
• Add runtime flags to NextConfigRuntime Pick in config-shared.ts so types reflect runtime behavior

Example use cases

• Expose an experimental client rendering toggle consumed by client components and edge routes
• Add a runtime-only optimization flag used inside app-render.tsx that must be read from process.env
• Create separate app runtime bundles to remove server-only branches from client-side route modules
• Fix a bug where a DefinePlugin entry unintentionally replaced an assignment in next-server.ts by scoping bundleType
• Validate and default a new boolean flag through zod to prevent misconfiguration in user next.config.js