Skip to content

Add nextjs vercel toolbar instructions (aligned with sveltekit) #328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vincent-derks merged 1 commit into from
Mar 11, 2026
Merged

Add nextjs vercel toolbar instructions (aligned with sveltekit) #328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions skills/flags-sdk/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,8 @@ Check the project state to decide which steps you can skip:
- Does `.vercel/` directory exist? → Project is linked, skip `vercel link` in step 2
- Does `.env.local` contain `FLAGS=`? → Env vars already pulled, skip step 3
- Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch (step 4)
- Does `app/.well-known/vercel/flags/route.ts` exist? → Flags Explorer already set up, skip step 6
- Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 6)
- Does `app/.well-known/vercel/flags/route.ts` exist? → Flags Explorer already set up, skip step 7

### Steps

Expand Down Expand Up @@ -109,7 +110,13 @@ Check the project state to decide which steps you can skip:
}
```

6. **Set up Flags Explorer** (if not already present): Create `app/.well-known/vercel/flags/route.ts` — see the [Flags Explorer setup](#flags-explorer-setup) section below.
6. **Set up the Vercel Toolbar** (if not already present):
- Run `pnpm i @vercel/toolbar`
- Wrap `next.config.ts` with the toolbar plugin
- Render `<VercelToolbar />` in the root layout
See [references/nextjs.md — Toolbar Setup](references/nextjs.md#toolbar-setup) for the full code.

7. **Set up Flags Explorer** (if not already present): Create `app/.well-known/vercel/flags/route.ts` — see the [Flags Explorer setup](#flags-explorer-setup) section below.

## Vercel Flags

Expand Down Expand Up @@ -311,7 +318,7 @@ import { FlagValues, FlagDefinitions } from 'flags/react';

Detailed framework and provider guides are in separate files to keep context lean:

- **[references/nextjs.md](references/nextjs.md)**: Next.js quickstart, App Router, Pages Router, middleware/proxy, precompute, dedupe, dashboard pages, marketing pages, suspense fallbacks
- **[references/sveltekit.md](references/sveltekit.md)**: SvelteKit quickstart, hooks setup, toolbar, precompute with reroute + middleware, dashboard pages, marketing pages
- **[references/nextjs.md](references/nextjs.md)**: Next.js quickstart, toolbar, App Router, Pages Router, middleware/proxy, precompute, dedupe, dashboard pages, marketing pages, suspense fallbacks
- **[references/sveltekit.md](references/sveltekit.md)**: SvelteKit quickstart, toolbar, hooks setup, precompute with reroute + middleware, dashboard pages, marketing pages
- **[references/providers.md](references/providers.md)**: All provider adapters — Vercel, Edge Config, Statsig, LaunchDarkly, PostHog, GrowthBook, Hypertune, Flagsmith, Reflag, Split, Optimizely, OpenFeature, and custom adapters
- **[references/api.md](references/api.md)**: Full API reference for `flags`, `flags/react`, `flags/next`, and `flags/sveltekit`
49 changes: 49 additions & 0 deletions skills/flags-sdk/references/nextjs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## Table of Contents

- [Quickstart](#quickstart)
- [Toolbar Setup](#toolbar-setup)
- [App Router](#app-router)
- [Pages Router](#pages-router)
- [Evaluation Context](#evaluation-context)
Expand Down Expand Up @@ -32,6 +33,52 @@ export const exampleFlag = flag({
});
```

## Toolbar Setup

1. Install `@vercel/toolbar`:

```sh
pnpm i @vercel/toolbar
```

2. Add Next.js plugin:

```ts
// next.config.ts
import type { NextConfig } from 'next';
import createWithVercelToolbar from '@vercel/toolbar/plugins/next';

const nextConfig: NextConfig = {};

const withVercelToolbar = createWithVercelToolbar();
export default withVercelToolbar(nextConfig);
```

3. Render toolbar in root layout:

```tsx
// app/layout.tsx
import { VercelToolbar } from '@vercel/toolbar/next';

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
// On Vercel, the toolbar is auto-injected in preview deployments.
// This manual injection is only needed for local development.
const shouldInjectToolbar = process.env.NODE_ENV === 'development';
return (
<html lang="en">
<body>
{children}
{shouldInjectToolbar && <VercelToolbar />}
</body>
</html>
);
}
```

## App Router

Call the flag function from any async server component or proxy:
Expand Down Expand Up @@ -432,6 +479,8 @@ The `hasAuthCookieFlag` checks cookie existence without authenticating. Two shel

## Flags Explorer (Next.js)

The Flags Explorer is part of the Vercel Toolbar. Before adding the discovery endpoint below, make sure the toolbar is set up by following the [Toolbar Setup](#toolbar-setup) steps first.

### App Router

```ts
Expand Down
Loading