From 3a6c61ca06c089983612097e62755dd12f1cf3c0 Mon Sep 17 00:00:00 2001
From: Vincent Derks <vincent.derks@vercel.com>
Date: Wed, 11 Mar 2026 17:15:05 +0100
Subject: [PATCH] Add nextjs vercel toolbar instructions (aligned with
 sveltekit)

---
 skills/flags-sdk/SKILL.md             | 15 +++++---
 skills/flags-sdk/references/nextjs.md | 49 +++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md
index 3a59c06d..d9826782 100644
--- a/skills/flags-sdk/SKILL.md
+++ b/skills/flags-sdk/SKILL.md
@@ -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
 
@@ -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
 
@@ -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`
diff --git a/skills/flags-sdk/references/nextjs.md b/skills/flags-sdk/references/nextjs.md
index dd9d9358..8a804e46 100644
--- a/skills/flags-sdk/references/nextjs.md
+++ b/skills/flags-sdk/references/nextjs.md
@@ -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)
@@ -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:
@@ -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