Overview

Layeron Feature Flags (featureFlags) helps you turn product behavior on and off without scattering conditional logic across your backend. You declare flags in application code, register the product with app.use(...), and evaluate flags from routes, jobs, modules, and product workflows.

Use Feature Flags for:

• Shipping a new feature to preview before production.
• Enabling a feature for a specific tenant or user.
• Rolling a feature out to a percentage of traffic.
• Choosing a variant for experiments or pricing pages.
• Storing small edge configuration values such as limits, modes, or copy keys.
• Protecting flag changes with Policy.

import { backend } from "@layeron/core"
import { featureFlags, flag } from "@layeron/modules"

const app = backend({ project: "shop" })

const flags = featureFlags({
  name: "main",
  namespace: "product",
  flags: {
    checkoutV2: flag.boolean({
      default: false,
      environments: {
        preview: true,
        prod: false,
      },
      rules: [
        flag.tenants(["tenant_123"]).value(true),
        flag.attribute("plan").equals("enterprise").value(true),
        flag.percentage(10, { stickiness: "userId" }).value(true),
      ],
    }),
  },
})

app.use(flags)

How You Use It

Evaluate a boolean flag:

const enabled = await flags.enabled("checkoutV2", {
  environment: "prod",
  tenantId: tenant.id,
  userId: user.id,
  attributes: {
    plan: tenant.plan,
  },
})

Read a typed value:

const maxUploadMb = await flags.value<number>("maxUploadMb", {
  tenantId: tenant.id,
  default: 25,
})

Ask for the full decision when you need to debug a rollout:

const decision = await flags.evaluate("checkoutV2", {
  userId: user.id,
  tenantId: tenant.id,
})

return Response.json({
  enabled: decision.value,
  reason: decision.reason,
  ruleId: decision.ruleId,
})

Core Ideas

Feature Flags has five user-facing concepts:

• Flag: A named value such as checkoutV2, pricingPageVariant, or maxUploadMb.
• Default: The value every request receives unless an environment or rule chooses a different value.
• Environment override: A value for preview, staging, prod, or any environment name your app uses.
• Rule: A tenant, user, attribute, or percentage condition that returns a value.
• Decision: The result of evaluating a flag, including the value and the reason that value was selected.

Evaluation Order

Feature Flags uses a predictable order:

1. Environment override.
2. Tenant rule.
3. User rule.
4. Attribute rule.
5. Percentage rollout rule.
6. Default value.

Keep specific rules above broad rollout rules so a tenant or user can receive a fixed experience while the rest of the audience follows the rollout.

Infrastructure From Code

Flags are part of your backend source. The catalog, default values, environment values, targeting rules, rollout percentages, audit setting, and Policy connection live in TypeScript.

The dashboard and CLI can inspect flags and show published state, but the source of truth is the application code that declares featureFlags(...).

Product Connections

Feature Flags works with the rest of your Layeron app:

• Policy can protect publishes, rollbacks, and admin reads.
• Observability helps you understand evaluation volume and publish events.
• Database and Storage keep the product state in your Cloudflare account as part of your app deployment.

Next Steps

• Get started: Define flags, evaluate values, target tenants and attributes, roll out percentages, and inspect decisions.
• Core concepts: Understand flags, defaults, environment overrides, rules, and decisions.
• Rules and rollouts: Target tenants, users, attributes, and percentages in rule order.
• Environments: Manage preview, staging, and production values with promotion habits.
• Policy: Protect read, publish, history, rollback, and admin paths.
• Publishing: Publish snapshots, inspect state, roll back, and audit updates.
• Examples: Adapt release, rollout, and runtime-limit examples.
• API reference: Review Feature Flags options, snapshots, decisions, history, rollback, and module methods.