bq-analytics-flags

bq-analytics feature flags

Flags live in a single Vercel Edge Config item under the key flags. The SDK reads at runtime via edgeConfigSource(); you mutate via the bq-flags CLI shipped in the package. Propagation is sub-second.

{
  "new-checkout":   { "on": true, "rollout": 0.5 },
  "ai-suggestions": { "on": true, "users": ["u_john", "u_beta1"] },
  "kill-old-flow":  { "on": false }
}

Detect current state

Before doing anything, figure out which path you're on:

Signal	What it means	Where to start
bq-analytics in package.json deps and EDGE_CONFIG= in .env.local	fully wired	jump to Operate
bq-analytics in deps, no EDGE_CONFIG=	events wired, flags not yet	Step 1 below
neither	greenfield	run /bq-analytics-install first; it handles flags as Phase 3

grep -E '"bq-analytics"' package.json && echo "sdk present"
grep -E '^EDGE_CONFIG=' .env.local 2>/dev/null && echo "edge config provisioned"

Step 1 — Add the flag dependency

pnpm add bq-analytics @vercel/edge-config
# or: npm i / yarn add

@vercel/edge-config is an optional peer of bq-analytics. Only needed when using edgeConfigSource() server-side; browser/RN clients use httpSource() and don't need it.

Step 2 — Provision Edge Config

./node_modules/bq-analytics/scripts/setup-edge-config.sh

What it does (idempotent — safe to re-run):

1. vercel link if not already linked
2. Creates an Edge Config store named bq-analytics-flags (or reuses one with that slug)
3. Initializes the flags key as {}
4. Mints a read token, pushes EDGE_CONFIG env var to Vercel Production
5. vercel env pull .env.local --environment production so local dev can read it

Note: only Production is set automatically (CLI quirk on preview/dev envs). For full env propagation, set VERCEL_TOKEN first, or replicate via the Vercel dashboard.

After this, bq-flags is available via pnpm exec bq-flags (or ./node_modules/.bin/bq-flags).