Rolling out a new feature

This workflow creates a Boolean feature flag, adds the entity context needed for bucketing, verifies the change in preview, and starts a staged rollout in production. The same rollout command works for String, Number, and JSON flags after you define their variants.

vercel flags create redesigned-checkout --kind boolean \
  --description "New checkout flow with streamlined steps"

Progressive rollouts bucket traffic by an entity attribute. In the dashboard, open Flags > Entities, create a User entity, and add an id attribute. The CLI examples on this page use --by user.id.

The environment variables include the Vercel OpenID Connect (OIDC) token used by the SDK. Pull them into your local .env.local:

vercel env pull

pnpm add flags @flags-sdk/vercel

Create a flag definition using the Flags SDK. The vercelAdapter connects the flag to Vercel Flags, and identify provides the entity data used for rollout bucketing:

import { dedupe, flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';
 
const identify = dedupe(async () => {
  const session = await getSession();
 
  return session?.user
    ? {
        user: {
          id: session.user.id,
        },
      }
    : {};
});
 
export const redesignedCheckout = flag({
  key: 'redesigned-checkout',
  adapter: vercelAdapter(),
  identify,
});

If user.id is missing for an evaluation, the rollout falls back to the configured fallback variant.

import { redesignedCheckout } from '../../flags';
 
export default async function CheckoutPage() {
  const showRedesign = await redesignedCheckout();
 
  return showRedesign ? <NewCheckout /> : <OldCheckout />;
}

vercel deploy

Visit the preview URL to confirm the old checkout renders. Preview still serves false until you change that environment.

When the preview deployment is ready, turn the flag on there for manual QA:

vercel flags enable redesigned-checkout --environment preview \
  --message "Verify redesigned checkout in preview"

Visit the preview URL again to confirm the new checkout renders.

vercel deploy --prod

vercel flags rollout redesigned-checkout --environment production --by user.id \
  --stage 5,6h --stage 10,6h --stage 25,12h --stage 50,1d \
  --message "Start redesigned checkout rollout"

Each --stage defines the percentage of traffic sent to the true variant and how long that stage lasts. After the last stage finishes, Vercel serves 100% of the true variant indefinitely by default. To end the rollout at a different percentage, pass --final-percentage. For example, --final-percentage 50 serves 50% of the true variant after the last stage. Final percentages below 100% require @vercel/flags-core version 1.9.0 or later. See --final-percentage for details.

Inspect the rollout at any time:

vercel flags inspect redesigned-checkout

To change the schedule, rerun vercel flags rollout with new --stage values. If you omit --start, --by, and the variant flags while updating an existing rollout, the CLI keeps the current values.

For String, Number, and JSON flags, choose the rollout variants explicitly. --from-variant, --to-variant, and --default-variant accept either a variant ID or a variant value, so for JSON flags it is often easier to pass the ID:

vercel flags rollout welcome-message --environment production --by user.id \
  --from-variant control --to-variant treatment --default-variant control \
  --stage 10,2h --stage 50,12h --start 2026-04-16T09:00:00Z