@supabase/middleware/feature-flag

Provider-agnostic feature-flag middleware. Pass any evaluate function — it's called per request, admits when the flag is on, rejects otherwise. Use it with PostHog, LaunchDarkly, Statsig, an env-var, a header, a database row — anything that can answer "is this flag enabled for this request?".

This is the worked example for authors. The implementation is short and well-commented — read with-feature-flag.ts alongside the authoring guide to see how each piece of defineMiddleware lands in practice.

import { withFeatureFlag } from '@supabase/middleware/feature-flag'

export default {
  fetch: withFeatureFlag(
    {
      name: 'beta-checkout',
      evaluate: (req) => req.headers.get('x-beta') === '1',
    },
    async (_req, ctx) => Response.json({ feature: ctx.featureFlag.name }),
  ),
}
Copy

Config

Returning richer verdicts

evaluate can return a verdict object to capture variant or payload:

withFeatureFlag({
  name: 'pricing-experiment',
  evaluate: async (req) => {
    const variant = await ld.variation('pricing-experiment', userKey, 'control')
    return { enabled: variant !== 'off', variant, payload: { rollout: 0.5 } }
  },
})
Copy

Then the handler reads:

ctx.featureFlag.variant // 'a' | 'b' | 'control' | null
ctx.featureFlag.payload // anything you returned
Copy

Why 404 by default

Soft reveal. A 403 Forbidden tells the caller "this exists, but you can't see it" — useful intel for an attacker probing for unreleased endpoints. 404 Not Found says "there's nothing here." Override via rejectStatus if you need stricter or different semantics.

Single namespace caveat

The middleware occupies ctx.featureFlag — only one withFeatureFlag can compose into a stack at a time. For multiple flags on the same route, write a single composite evaluator that returns a richer verdict, or run separate routes per flag.

See also

• Authoring guide
• Composition primitives