Draft Flags

Drafts are flags that Vercel detects in your code but haven't been created in the dashboard yet. They let you define flags in code first, then configure them in the dashboard when you're ready.

When you deploy your application, Vercel queries your Flags Discovery Endpoint to detect flags defined in code. If a flag has its provider set to Vercel but doesn't exist in the dashboard, it appears as a draft.

This happens automatically when:

1. You define a flag in code using the Flags SDK with vercelAdapter()
2. Your application exposes a Flags Discovery Endpoint
3. You deploy to production

When a flag is in draft state, Vercel knows it exists but doesn't control its value yet. Your application evaluates the flag using the defaultValue you defined in code. No targeting rules, segments, or environment-specific configuration apply until you create a Vercel Flag from the draft.

This lets you ship code with new flags before deciding how to configure them. For example, you might deploy a flag with defaultValue: false to keep the feature hidden, then promote and configure targeting rules when you're ready to roll out.

export const newCheckout = flag({
  key: 'new-checkout',
  adapter: vercelAdapter(),
  defaultValue: false, // Used while the flag is a draft
  description: 'Enable the new checkout flow',
  options: [
    { value: true, label: 'Enabled' },
    { value: false, label: 'Disabled' },
  ],
});

The description and options you define here will pre-fill the dashboard when you promote the draft.

Vercel compares the flags in your code against the flags in the dashboard whenever a new production deployment goes live. It uses the Flags Discovery Endpoint to detect which flags your code defines, then highlights any mismatches:

• Drafts: Flags that exist in your production deployment's code but have not been created in the dashboard appear as drafts. You can promote a draft to turn it into a fully managed Vercel Flag with targeting rules and environment configuration.
• Unreferenced: Flags that exist in the dashboard but are not found in your latest production deployment are marked with an Unreferenced badge in the flag list and flag details page. This helps you identify flags that may be safe to archive.
• Referenced archived flags: If an archived flag is still present in your production deployment, the archive shows a Referenced badge so you know the code still depends on it. This can indicate a potential misconfiguration since archived flags are neither served nor evaluated, so your application will fall back to the default value defined in code.

To start managing a flag through the dashboard:

1. Navigate to the Flags tab in your project
2. Go to the Drafts section
3. Click on the draft you want to promote
4. Click Create Flag

When you promote a draft, Vercel pre-fills the flag configuration with information from your code:

• Description: From the description property in your flag definition
• Options/Variants: From the options array in your flag definition
• Type: Inferred from your default value or options

After promotion, the flag is managed by the dashboard and you can configure environments, add targeting rules, and track changes.

Vercel detects drafts through your application's Flags Discovery Endpoint, typically located at /.well-known/vercel/flags. This endpoint returns metadata about your flags, including:

• Flag keys
• Descriptions
• Available options
• Provider information

If you're using the Flags SDK, use getProviderData to generate this information automatically:

import { createFlagsDiscoveryEndpoint, verifyAccess } from 'flags/next';
import { getProviderData } from '@flags-sdk/vercel';
import * as flags from '../../../../flags';
 
export const GET = createFlagsDiscoveryEndpoint(async () => {
  return getProviderData(flags);
});

• Configure your flags
• Learn about the Flags SDK