Feature Flag

The @talosjs/feature-flag component is a small, typed contract for gating functionality behind toggles. Each flag is an injectable class implementing the IFeatureFlag interface (getKey, getDescription, and isEnabled), registered with a decorator and resolved from the container. The enablement check can be synchronous or asynchronous, so a flag can return a constant, read an environment variable, or query a remote service.

What it offers

Every flag implements the same IFeatureFlag interface, so call sites evaluate them identically no matter how each flag reaches its decision. isEnabled() may return a boolean or a Promise<boolean>, which lets you back a flag with a constant, an env var, config, or a remote check without changing the callers. Each flag also carries a stable getKey() and a human-readable getDescription(), so the set of flags stays discoverable and auditable. Registration is a decorator, the DI container resolves the flag at any scope, and the types (IFeatureFlag and FeatureFlagClassType) are there throughout.

How it works

You implement IFeatureFlag as a class, register it with the featureFlag decorator, and resolve it from the container. Callers invoke isEnabled() and branch on the result.

Method	Purpose
`getKey()`	Return a unique, stable identifier for the flag (kebab-case by convention).
`getDescription()`	Return a human-readable explanation of what the flag controls.
`isEnabled()`	Decide whether the flag is on; returns `boolean` or `Promise<boolean>`.

The interface is the whole contract:

interface IFeatureFlag {
  getKey: () => string;
  getDescription: () => string;
  isEnabled: () => Promise<boolean> | boolean;
}

Because isEnabled() can be async, the same flag shape covers constant toggles, environment-driven rollouts, and remote configuration. Callers always await the result and never need to know the source.

Decorator and usage

`@decorator.featureFlag(scope?)`

Registers a feature-flag class with the DI container. It accepts an optional EContainerScope (defaults to EContainerScope.Singleton). Implement IFeatureFlag and register it:

import { decorator, type IFeatureFlag } from "@talosjs/feature-flag";

@decorator.featureFlag()
export class DarkModeFeatureFlag implements IFeatureFlag {
  public getKey(): string {
    return "dark-mode";
  }

  public getDescription(): string {
    return "Enables the dark mode theme";
  }

  public isEnabled(): boolean {
    return true;
  }
}

isEnabled() can resolve a value from a remote service, database, or environment:

import { decorator, type IFeatureFlag } from "@talosjs/feature-flag";

@decorator.featureFlag()
export class BetaCheckoutFeatureFlag implements IFeatureFlag {
  public getKey(): string {
    return "beta-checkout";
  }

  public getDescription(): string {
    return "Enables the redesigned checkout flow for beta users";
  }

  public async isEnabled(): Promise<boolean> {
    return process.env.BETA_CHECKOUT === "true";
  }
}

Resolve the flag from the container and branch on the result:

import { container } from "@talosjs/container";
import { DarkModeFeatureFlag } from "./DarkModeFeatureFlag";

const flag = container.get(DarkModeFeatureFlag);

if (await flag.isEnabled()) {
  // ...render dark mode
}

Pass a scope when a flag should not be a singleton, for example to re-evaluate it per request:

import { EContainerScope } from "@talosjs/container";
import { decorator, type IFeatureFlag } from "@talosjs/feature-flag";

@decorator.featureFlag(EContainerScope.Transient)
export class ExperimentalFeatureFlag implements IFeatureFlag {
  public getKey(): string {
    return "experimental";
  }

  public getDescription(): string {
    return "Enables experimental features";
  }

  public isEnabled(): boolean {
    return false;
  }
}

Using flags well

Keep keys stable and unique. Use kebab-case like dark-mode and beta-checkout, and never reuse or rename a key once it ships, because logs and config may reference it. Write a real description, since getDescription() is what makes flags auditable: say what the flag controls and who it targets, not just its name. Treat isEnabled() as potentially async even for constant flags and always await it, so a flag can later move to a remote check without touching callers. Keep the decision in one place. All gating logic belongs inside isEnabled(), and callers should only branch on the boolean rather than re-deriving the condition. Match the scope to the source: the default singleton suits constant or env-driven flags, while Transient or Request fits a flag that must be re-evaluated per request. When a flag reads config or calls a service, inject those dependencies through the constructor instead of reaching for globals.

CLI command

Scaffold a feature flag class and its test file with the generator. It writes the class under modules/<module>/src/flags/<Name>FeatureFlag.ts and installs @talosjs/feature-flag if it is missing.

# Interactive: prompts for the name
talos flag:create

# Provide the name
talos flag:create --name=NewCheckout

# Target a module and overwrite
talos flag:create --name=NewCheckout --module=checkout --override

Option	Description	Default
`--name`	Feature flag class name. The `FeatureFlag` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class is a ready-to-complete stub with the key pre-filled in kebab-case from the name:

import { decorator, type IFeatureFlag } from "@talosjs/feature-flag";

@decorator.featureFlag()
export class NewCheckoutFeatureFlag implements IFeatureFlag {
  public getKey(): string {
    return "new-checkout";
  }

  public getDescription(): string {
    return "";
  }

  public isEnabled(): Promise<boolean> | boolean {
    return false;
  }
}

See flag:create for the full command reference.

Use with Claude and Codex

The generator ships a matching flag:create skill. It runs the scaffold and then guides your AI agent through completing the flag: setting a stable key, writing the description, and implementing isEnabled() with the real gating logic. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a feature flag that enables the new checkout flow.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a feature flag that enables the new checkout flow.

For example, the prompt above maps to flag:create --name=NewCheckout, then implements getKey, getDescription, and isEnabled for the new checkout flow.

Getting Started

AI

Framework

Command Line

Feature Flag

What it offers

How it works

Decorator and usage

`@decorator.featureFlag(scope?)`

Using flags well

CLI command

Use with Claude and Codex

​What it offers

​How it works

​Decorator and usage

​@decorator.featureFlag(scope?)

​Using flags well

​CLI command

​Use with Claude and Codex

What it offers

How it works

Decorator and usage

`@decorator.featureFlag(scope?)`

Using flags well

CLI command

Use with Claude and Codex