Docs:

[Tigatok]

What is the documentation issue?

I think we can clear up some of the flags documentation to list what is required for what and where.

Is there any context that might help us understand?

I find the whole flags documentation a bit confusing. The first section outlines how to set up the Flags SDK in NextJS. It says the following:

If you set an override for this feature flag using Vercel Toolbar, then the feature flag will respect the override and will not invoke the decide function.

I tried to follow that guide, as well as the Manage Flags from the Toolbar guide, but my overrides don't seem to apply automatically. I'm probably just misunderstanding the docs somewhere, but I am not sure. Seems like I've set things up properly.

// src/flag.ts
import { unstable_flag as flag } from '@vercel/flags/next'

import { getFlags } from './app/getFlags'

export const myFlag = flag({
  key: 'my-flag',
  decide: () => false,
  description: 'My Flag',
  origin: 'https://example.com/#new-feature',
}

// src/app/layout.tsx

export default async function Layout({
  children, // will be a page or nested layout
}: {
  children: React.ReactNode
}) {
  const enableMyFlag = await myFlag()
  console.log('myFlag', enableMyFlag)

import { NextResponse, type NextRequest } from 'next/server'
import { verifyAccess, type ApiData } from '@vercel/flags'

export async function GET(request: NextRequest) {
  const access = await verifyAccess(request.headers.get('Authorization'))
  if (!access) return NextResponse.json(null, { status: 401 })

  return NextResponse.json<ApiData>({
    definitions: {
      myFlag: {
        description: 'My Flag',
        origin: 'https://example.com/#new-feature',
        options: [
          { value: false, label: 'Off' },
          { value: true, label: 'On' },
        ],
      },
    },
  })
}

When I console log my flag in my layout, regardless of my toolbar overrides it shows False. I am not sure where I am going wrong.

TIA

Does the docs page already exist? Please link to it.

https://vercel.com/docs/workflow-collaboration/feature-flags/flags-pattern-nextjs#overrides-apply-automatically

[Tigatok]

Is it proper or expected of me to add my getFlags call in my src/flags.ts file in the decide function? So like the following:

import { unstable_flag as flag } from '@vercel/flags/next'
import { get } from '@vercel/edge-config'
import { getFlags } from './app/getFlags'

export const myFlag = flag({
  key: 'enable-myflag',
  async decide() {
    const overrides = await getFlags()

    if (overrides.myFlag !== undefined) {
      return overrides.myFlag
    }

    const value = await get('enable-myflag')
    return value ?? false
  },
})

[samcx]

@Tigatok Thank you for the feedback! I will share this with the team.

I moved this out of Next.js issues since this is also technically related to Vercel documentation, not Next.js documentation itself (nextjs.org/docs).

That seems right, with Edge Config. From our docs →

import { unstable_flag as flag } from '@vercel/flags/next';
import { get } from '@vercel/edge-config';
 
export const showSummerSale = flag({
  key: 'summer-sale',
  async decide() {
    const value = await get('summer-sale'); // could use this.key instead
    return value ?? false;
  },
});

The guide is sort of set up to first have a decide: ... always set to false. Then you can use the Vercel Toolbar to override it locally, to see the difference. Then the guide pivots to setting up Middleware and Edge Config to change the flag, for your users. The Toolbar I believe is technically just your testing purposes, not for your users (that's why it's overriding the decide: .... You need to toggle it separately for your users.

Let me know if that help clarifies!

[AAorris]

Hi @Tigatok, thanks for trying out the Flags SDK. 🙇

The issue here is likely a mismatch between the key of your flags in the .well-known route and your flag definition:

// flag.ts
export const myFlag = flag({
  key: 'my-flag', // <-- Key is provided as "my-flag"
  decide: () => false,
  description: 'My Flag',
  origin: 'https://example.com/#new-feature',
}

// .well-known/vercel/flags/route.ts
return NextResponse.json<ApiData>({
  definitions: {
    myFlag: {  // <-- Key is provided as "myFlag"
      description: 'My Flag',
      origin: 'https://example.com/#new-feature',
      options: [
        { value: false, label: 'Off' },
        { value: true, label: 'On' },
      ],
    },
  },
})

To help prevent this, you can use unstable_getProviderData to convert your flags to definitions. It works like this:

// app/flags.ts
export const myFlag = flag({key: 'my-flag'})

// .well-known/vercel/flags/route.ts
import { verifyAccess, type ProviderData } from '@vercel/flags';
import { unstable_getProviderData as getProviderData } from '@vercel/flags/next';
import { NextResponse } from 'next/server';
import * as flags from '#/app/flags'; // update this to point to where you export your flags

export const GET = async (request: Request): Promise<Response> => {
  const access = await verifyAccess(request.headers.get('Authorization'));
  if (!access) return NextResponse.json(null, { status: 401 });

  return NextResponse.json<ProviderData>(getProviderData(flags));
};

I expect you will see overrides working in the toolbar with this change, and you won't have to worry about getting the key right in the future. If you define all your flags in one place, you won't have to update the route.ts in the future either.

[adg29]

Hi @AAorris essential insight, thank you! If I had not bumped into this thread, I would still be going in circles to integrate the flags SDK and Vercel Toolbar into my my NextJS app.

The wasted cycles on my end are partly due to the rather generic/vague docs re the vercel/nextjs integration.

Point in case:

Neither of the resources below emphasize

• the importance of matching the .well-known route and the flag definition
• that flags declared using unstable_flag can easily by turned into Vercel Toolbar compatible definitions using unstable_getProviderData

https://vercel.com/docs/workflow-collaboration/feature-flags/supporting-feature-flags#verifying-a-request-to-the-api-endpoint
https://vercel.com/docs/workflow-collaboration/feature-flags/implement-flags-in-toolbar#creating-the-flags-api-endpoint