$flag

This small utility provides an environment-aware feature flags with full type safety and convenience. It's built to handle both simple boolean flags and advanced per-environment configurations.

Usage

const { $flag } = defineFlags({
    useBetaFeature: true,
    showDebugTools: {
        dev: true,
        test: false,
        prod: false,
    },
})

if ($flag("showDebugTools")) {
    // Enable debug tools in dev
}

API

defineFlags(flags)

Takes a typed record of flags and returns an object containing:

• $flag(name: string): boolean
• flags: The original flag definitions for reference/debugging

Supported Flag Types

type Envs = Record<"dev" | "test" | "prod", boolean>
type FlagValue = boolean | Envs

• boolean: Always on/off.
• Envs: Scoped flags per environment.

Environment Handling

Environment is determined using process.env.NODE_ENV and import.meta.test. Resolution priority:

1. development → uses val.dev
2. production → uses val.prod
3. Test environment → uses val.test (only if import.meta.test is true)
4. Any other case returns false

Example

const { $flag } = defineFlags({
    enableLogging: {
        dev: true,
        test: false,
        prod: false,
    },
    feature: () => false // run functions too
    disableAnalytics: false,
})

$flag("enableLogging") // → true in development
$flag("disableAnalytics") // → false always