Feature Flags

Backend-evaluated feature flags for Convex with boolean kill-switches, multivariate variants, percentage rollouts, and attribute targeting streamed to clients i

Installation

npm install @vllnt/convex-flags

About Feature Flags

Feature Flags brings backend-evaluated flagging to Convex: boolean kill-switches, multivariate variants, weighted percentage rollouts, attribute targeting, and per-subject overrides — flipped with a single mutation, no redeploy and no third-party flag SaaS. Because flags are evaluated inside Convex queries, every change streams to connected clients over the same reactive subscriptions as your app data. Definitions and overrides live in the component's own sandboxed tables (zero blast radius into your schema), the host gates every management call, and it runs identically on Convex Cloud and self-hosted convex-backend.

Benefits

Evaluate feature flags inside Convex queries so changes propagate to all connected clients over existing reactive subscriptions without a redeploy
Target flag values with ordered attribute rules and per-subject overrides, supporting eq, in, contains, and gt operators over host-supplied context
Isolate flag definitions and overrides in sandboxed component tables that never read from or write to your application schema
Consume flags from React with useFlag and useFlags hooks, or from any backend function with zero React dependency

Use cases

how to add feature flags to a Convex app without a third-party service

The @vllnt/convex-flags component runs entirely inside your Convex deployment. Install the package, register the component in convex.config.ts, instantiate Flags in a convex/flags.ts file, and call flags.define to create a flag and flags.isEnabled or flags.evaluate inside any query. No external SaaS account or API key is needed.

real-time feature flag updates in Convex without polling

Because @vllnt/convex-flags evaluates flags inside Convex queries, any flag change triggers the same reactive push that updates your application data. Clients subscribed to a query that calls flags.evaluate or flags.isEnabled receive the updated value automatically over the existing WebSocket connection.

percentage rollout and A/B testing in Convex backend

Define a flag with a rollout field specifying weighted splits, for example 50 percent true and 50 percent false. Pass a subjectRef when calling flags.isEnabled or flags.evaluate to get stable per-subject bucketing, so the same user always lands in the same cohort across evaluations.

how to override a feature flag for a specific user in Convex

Call flags.setOverride with the flag key, a subjectRef identifying the user, and the forced value. The override takes the highest precedence in evaluation order, before targeting rules, rollout, and the default flag value. Call flags.clearOverride to remove it.

Frequently asked questions

Does @vllnt/convex-flags require a third-party feature flag service like LaunchDarkly or Statsig?

@vllnt/convex-flags is self-contained and runs entirely inside your Convex deployment. All flag definitions, targeting rules, rollout configuration, and per-subject overrides are stored in the component's own sandboxed tables. No external service, API key, or webhook is involved.

How does @vllnt/convex-flags handle authentication and authorization for flag management?

@vllnt/convex-flags is auth-agnostic. All management methods such as define, enable, disable, archive, and setOverride are internal to the component. You wrap them in your own Convex mutations and apply your authorization logic there before delegating to the component, so the component never makes auth decisions on your behalf.

Can @vllnt/convex-flags be used from React components?

Yes. The package ships an optional ./react entry point exporting useFlag and useFlags hooks. Both hooks accept the evaluate query you export from your convex/flags.ts file and return a FlagEvaluation object. React is an optional peer dependency, so backend-only consumers do not pull in React.

What evaluation order does @vllnt/convex-flags use when resolving a flag value?

@vllnt/convex-flags resolves flags in this order: per-subject override, archived state, ordered targeting rules, fallthrough rollout, then the flag's base value. If the flag key does not exist, the caller's provided default or false is returned.

Does @vllnt/convex-flags work on self-hosted Convex deployments?

Yes. @vllnt/convex-flags runs unchanged on both Convex Cloud and self-hosted convex-backend deployments. The only peer dependency is convex at version 1.36.1 or later.