FlagSim

Interactive feature flag simulator for testing targeting rules, rollout percentages, identity continuity, and multivariate assignment.

Repository: https://github.com/ezeigboemmanuel/flagsim

What It Does

• Build flags with condition groups.
• Use OR logic across groups and AND logic inside a group.
• Test operators such as equals, not equals, contains, greater than, less than, is set, and regex.
• Simulate deterministic bucketing using distinct_id and flag key hashing.
• Evaluate boolean and multivariate flags.
• Compare anonymous and identified users in continuity mode.
• Run bulk evaluations from JSON input.
• Persist simulator state in browser localStorage.

Tech Stack

• React 19
• TypeScript
• Vite
• Tailwind CSS
• Radix UI primitives

Getting Started

Prerequisites

• Node.js 18+ (Node.js 20+ recommended)
• npm

Install

npm install

Run In Development

npm run dev

Open the local URL printed by Vite (usually http://localhost:5173).

Build For Production

npm run build

Preview Production Build

npm run preview

Lint

npm run lint

Usage

1. Configure your flag in Flag Builder:

• Add one or more groups.
• Add conditions inside each group.
• Set group rollout percentages.
• Choose boolean or multivariate flag type.

2. Choose a test mode:

• Custom: evaluate one user by distinct_id and properties.
• Continuity: compare anonymous_id vs identified_id assignment.
• Bulk: evaluate multiple users via JSON array.

3. Click Evaluate to view:

• Match status.
• Matched group.
• Bucket value.
• Returned variant/result.

Bulk Input Example

[
  {
    "distinct_id": "user-1",
    "plan": "premium",
    "country": "US",
    "email": "a@posthog.com"
  },
  {
    "distinct_id": "user-2",
    "plan": "free",
    "country": "US",
    "email": "b@example.com"
  },
  {
    "distinct_id": "user-3",
    "plan": "premium",
    "country": "CA",
    "email": "c@example.com"
  }
]

Project Structure

• src/App.tsx: Main simulator page and orchestration.
• src/lib/evaluator.ts: Flag evaluation engine and bucket logic.
• src/components/simulator/: UI for flag configuration, test user modes, and result rendering.
• src/lib/userProperties.ts: User property entry conversion utilities.

Notes

• Distinct IDs are required for deterministic bucketing.
• In bulk mode, each object should include distinct_id.
• State is saved locally in the browser under a simulator storage key.

License

MIT. See LICENSE.