Flags

Copy codeconst flags = new Flags(components.flags);
await flags.define(ctx, { key: "new-checkout", value: false });
await flags.enable(ctx, "new-checkout");
const on = await flags.isEnabled(ctx, "new-checkout", { subjectRef: userId }); // reactive in a query

Copy codenpm install @vllnt/convex-flags

Copy codeimport { defineApp } from "convex/server";
import flags from "@vllnt/convex-flags/convex.config";

const app = defineApp();
app.use(flags);
export default app;

Copy code// convex/flags.ts — instantiate once, then re-export the public function refs the
// rest of your app (and the React hooks) call. The host owns auth: gate the
// management mutations here before delegating to the component.
import { v } from "convex/values";
import { Flags } from "@vllnt/convex-flags";
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";

export const flags = new Flags(components.flags);

// Evaluation queries — reactive; `api.flags.evaluate` is what the React hooks below use.
export const evaluate = query({
  args: { key: v.string(), context: v.optional(v.any()), default: v.optional(v.any()) },
  handler: (ctx, args) =>
    flags.evaluate(ctx, args.key, { context: args.context, default: args.default }),
});

export const all = query({
  args: { context: v.optional(v.any()) },
  handler: (ctx, args) => flags.all(ctx, args.context),
});

// Management mutations — apply your own auth check before delegating.
export const define = mutation({
  args: { key: v.string(), value: v.any() /* + description/variants/rules/rollout */ },
  handler: (ctx, args) => {
    // assertAdmin(ctx);
    return flags.define(ctx, args);
  },
});

// Wrap the rest the same way — `update`, `enable`, `disable`, `archive`,
// `restore`, `setOverride`, `clearOverride` — each gated then delegated.

Copy code// Flags are data — create them from your own authorized mutations (host owns auth),
// then evaluate inside any query, mutation, or action.
import { query } from "./_generated/server";
import { flags } from "./flags";

// A targeted rollout: pro users get the new checkout; everyone else is a 50/50 split.
export const setup = async (ctx) => {
  await flags.define(ctx, {
    key: "new-checkout",
    value: false,
    rules: [{ conditions: [{ attribute: "plan", op: "eq", values: ["pro"] }], value: true }],
    rollout: { splits: [{ value: true, weight: 50 }, { value: false, weight: 50 }] },
  });
};

export const checkout = query({
  args: {},
  handler: async (ctx) =>
    (await flags.isEnabled(ctx, "new-checkout", { subjectRef: "user-123", attributes: { plan: "free" } }))
      ? loadNewCheckout(ctx)
      : loadLegacyCheckout(ctx),
});

Copy codeimport { useFlag } from "@vllnt/convex-flags/react";
import { api } from "../convex/_generated/api";

// api.flags.evaluate is the query exported in convex/flags.ts (Usage, above).
const checkout = useFlag(api.flags.evaluate, "new-checkout", { context: { subjectRef: userId } });
if (checkout?.value === true) { /* render the new checkout */ }

Copy codepnpm test           # single run
pnpm test:coverage  # enforced 100% on covered files