Feature flags / dead-code elimination

[yamcodes]

Summary

Dedicated RFC and Hat evaluation to design first-class Compile-Time Dead-Code Elimination (DCE) for Client Feature Flags across Next.js, Nuxt, Vite, and Bun.

Spun out from the Next.js S-Tier architecture evaluation (PR #1613 / docs/design/nextjs-codegen-runtime-evaluation.md) to give feature flags the focused design evaluation they deserve without cluttering the core virtual placement foundation.

---

The Problem Statement

1. Object Reads Opaque to Minifiers:
   • In standard application code, if (env.NEXT_PUBLIC_ENABLE_BETA) reads from an imported object / runtime Proxy.
   • Minifiers (SWC/Turbopack, Terser, ESBuild, Rollup) cannot constant-fold cross-module object property reads, leaving heavy unused component chunks in the client JavaScript bundle even when a feature flag is disabled ("false").
2. The Double-Stutter Developer Friction:
   • Requiring isEnabled("NEXT_PUBLIC_FLAG", process.env.NEXT_PUBLIC_FLAG) creates repetitive, stuttering syntax and forces developers to write raw process.env in their components.

---

Design Candidates (The Hat)

Candidate 1: Single-Arg Generated isEnabled("KEY")

In client component:

import { isEnabled } from "@/env";

if (isEnabled("NEXT_PUBLIC_ENABLE_BETA")) {
  return <HeavyBetaModule />;
}

• Mechanism: .arkenv/index.ts generates an inlinable switch-case function containing literal process.env.NEXT_PUBLIC_* identifiers.
• Minifier inlining: Turbopack inlines the function call + identifier $\to$ "false" === "true" $\to$ false $\to$ drops the branch.

Candidate 2: Generated flags Object

import { flags } from "@/env";

if (flags.NEXT_PUBLIC_ENABLE_BETA) {
  return <HeavyBetaModule />;
}

Candidate 3: Direct Named Boolean Const Exports

import { IS_BETA } from "@/env/flags";

---

Acceptance Criteria

• Technical spike and minifier benchmark comparing Candidate 1 vs. Candidate 2 vs. Candidate 3 across:
  • Next.js 16 (Turbopack + SWC)
  • Vite 6 / Rollup
  • Nuxt 3 / Nitro
  • Bun
• Measure actual production client chunk bundle sizes before and after DCE.
• Verify zero TypeScript generic boilerplate in user components.
• Finalize RFC and implement in a dedicated PR.

---

Converted from issue #1599 (not hashed out / RFC → Discussion).

[yamcodes]

Drop or wait for Post-v1 (or build it as a standalone package)