Production Feature Flags for Next.js

You are working in REPLACE_WITH_REPOSITORY.

Your task is to add production-ready GrowthBook feature flags to this Next.js
App Router application while preserving current behavior and a known-safe
fallback.

Read REPLACE_WITH_GUIDE_URL in full before editing. Also read the repository's
local agent instructions. Treat the operator's instructions, repository truth,
and current official product/framework documentation as authoritative when they
conflict with the guide. Revalidate the guide's tested versions and volatile
surfaces before copying an executable step.

Inspect the repository first. Adapt the reference implementation to its existing
identity, analytics, logging, secrets, tests, and deployment conventions; do not
blindly overwrite files or invent credentials, identifiers, metrics, or domains.
Complete phase 0 and the safe, non-production parts of phase 1. Do not perform a
production deployment, enable production traffic, or make another external write
unless I explicitly authorize that exact action.

Return: your fit or reject decision; assumptions; files changed; commands and
tests run; feature-delivery, identity, parity, exposure, failure, and rollback
receipts; deviations from the guide; and the remaining manual or production
steps. If you cannot fetch the guide URL, stop and ask me for its Markdown
version. Do not proceed from the TL;DR alone.

.env.local
src/proxy.ts
src/lib/auth/viewer.ts
src/lib/feature-flags/attributes.ts
src/lib/feature-flags/telemetry.ts
src/lib/feature-flags/flags.ts
src/app/checkout/page.tsx
src/app/checkout/checkout-client.tsx
src/app/api/checkout/config/route.ts
src/lib/feature-flags/evaluation.test.ts
src/lib/feature-flags/attributes.test.ts
tests/feature-flag-parity.spec.ts

node --version
npm ls next react react-dom --depth=0
find src app pages -maxdepth 3 -type f 2>/dev/null | sort | sed -n '1,200p'
grep -R "use client" -n src/app app 2>/dev/null | sed -n '1,120p'
grep -R "cookies()\|headers()\|export async function \(GET\|POST\)" -n src/app app 2>/dev/null | sed -n '1,160p'
grep -R "FEATURE_\|FLAG_\|process\.env.*CHECKOUT\|Math\.random" -n src app pages 2>/dev/null | sed -n '1,160p'

node --version
npm ls next react react-dom --depth=0
rg --files src app pages 2>$null | Select-Object -First 200
rg -n 'use client|cookies\(\)|headers\(\)|export async function (GET|POST)' src app 2>$null
rg -n 'FEATURE_|FLAG_|process\.env.*CHECKOUT|Math\.random' src app pages 2>$null

Does any flag decision protect server behavior or sensitive rules?
|
+-- Yes --> Evaluate on the server.
|           |
|           +-- Using Next.js App Router with Vercel Flags conventions?
|           |     |
|           |     +-- Yes --> Use @flags-sdk/growthbook as the primary path.
|           |     +-- No  --> Use @growthbook/growthbook directly on the server.
|           |
|           +-- Does a Client Component need the value?
|                 |
|                 +-- Only for rendering/actions --> Pass the resolved primitive as a prop.
|                 +-- It must evaluate independently --> Hydrate a decrypted payload and identical
|                                                       attributes, or use front-end remote evaluation.
|
+-- No --> Is the application front-end-only?
            |
            +-- Yes --> Use @growthbook/growthbook-react.
            +-- No  --> Prefer server evaluation and pass the result down.

GROWTHBOOK_CLIENT_KEY="sdk_REPLACE_WITH_DEV_KEY"
GROWTHBOOK_API_HOST="https://cdn.growthbook.io"

# Optional. Set only if SDK payload encryption is enabled for this connection.
GROWTHBOOK_DECRYPTION_KEY=""

# Optional. Used only to pseudonymize diagnostic unit ids in this guide.
FEATURE_TELEMETRY_HASH_KEY="replace-with-a-random-server-only-secret"

node -e "for (const k of ['GROWTHBOOK_CLIENT_KEY']) { if (!process.env[k]) process.exitCode = 1; console.log(k, process.env[k] ? 'set' : 'missing') }"

GROWTHBOOK_CLIENT_KEY set

Key: new-checkout-flow
Type: Boolean
Description: Owner: Checkout team. Remove after the new checkout is the code default and the rollback window closes.
Default value: false

npm install @flags-sdk/growthbook@0.3.1 flags@4.3.0
npm install --save-dev vitest@4.1.10 @playwright/test@1.62.1

added ... packages
found 0 vulnerabilities

import { NextResponse, type NextRequest } from "next/server";

const COOKIE_NAME = "gb_anon_id";
const REQUEST_HEADER = "x-gb-anon-id";
const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;

export function proxy(request: NextRequest) {
  const existingId = request.cookies.get(COOKIE_NAME)?.value;
  if (existingId) return NextResponse.next();

  const anonymousId = crypto.randomUUID();
  const requestHeaders = new Headers(request.headers);

  // The new cookie is not visible to this request, so forward the same value
  // in an internal request header for the first render.
  requestHeaders.set(REQUEST_HEADER, anonymousId);

  const response = NextResponse.next({
    request: { headers: requestHeaders },
  });

  response.cookies.set({
    name: COOKIE_NAME,
    value: anonymousId,
    httpOnly: true,
    sameSite: "lax",
    secure: process.env.NODE_ENV === "production",
    path: "/",
    maxAge: ONE_YEAR_SECONDS,
  });

  return response;
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml|.*\\..*).*)",
  ],
};

curl -sS -D - http://localhost:3000/checkout -o /dev/null | grep -i '^set-cookie: gb_anon_id='

set-cookie: gb_anon_id=...; Path=/; ...; HttpOnly; SameSite=lax

export interface Viewer {
  userId: string;
  organizationId?: string;
  plan?: "free" | "pro" | "enterprise";
  isEmployee: boolean;
}

/**
 * Anonymous-only default. Replace this function with the application's
 * authoritative server-side session lookup before using authenticated rules.
 */
export async function getViewer(): Promise<Viewer | null> {
  return null;
}

import { auth } from "@/auth";

export interface Viewer {
  userId: string;
  organizationId?: string;
  plan?: "free" | "pro" | "enterprise";
  isEmployee: boolean;
}

export async function getViewer(): Promise<Viewer | null> {
  const session = await auth();
  const user = session?.user;
  if (!user?.id) return null;

  return {
    userId: user.id,
    organizationId: user.organizationId ?? undefined,
    plan: user.plan ?? undefined,
    isEmployee: user.roles?.includes("employee") ?? false,
  };
}

import type { Attributes } from "@flags-sdk/growthbook";
import type { Identify } from "flags";
import { dedupe } from "flags/next";
import { cookies, headers } from "next/headers";
import { getViewer, type Viewer } from "@/lib/auth/viewer";

const COOKIE_NAME = "gb_anon_id";
const REQUEST_HEADER = "x-gb-anon-id";

export interface AppAttributes extends Attributes {
  id: string;
  anonymous_id: string;
  user_id: string;
  organization_id: string;
  employee: boolean;
  plan: "anonymous" | "free" | "pro" | "enterprise";
  identity_ready: boolean;
}

export function buildGrowthBookAttributes(
  anonymousId: string | undefined,
  viewer: Viewer | null,
): AppAttributes {
  const stableAnonymousId = anonymousId ?? "";
  const userId = viewer?.userId ?? "";

  return {
    // This canonical example switches the primary id at login. See the identity
    // section before using id as an experiment hash attribute.
    id: userId || stableAnonymousId || "missing-identity",
    anonymous_id: stableAnonymousId,
    user_id: userId,
    organization_id: viewer?.organizationId ?? "",
    employee: viewer?.isEmployee ?? false,
    plan: viewer?.plan ?? (viewer ? "free" : "anonymous"),
    identity_ready: Boolean(userId || stableAnonymousId),
  };
}

export const getRequestAttributes = dedupe(async () => {
  const [cookieStore, headerStore, viewer] = await Promise.all([
    cookies(),
    headers(),
    getViewer(),
  ]);

  const anonymousId =
    cookieStore.get(COOKIE_NAME)?.value ??
    headerStore.get(REQUEST_HEADER) ??
    undefined;

  return buildGrowthBookAttributes(anonymousId, viewer);
});

export const identify = getRequestAttributes satisfies Identify<AppAttributes>;

import { createHmac } from "node:crypto";

type JsonScalar = string | number | boolean | null;

export interface FeatureEvaluationReceipt {
  featureKey: string;
  value: JsonScalar;
  source: string;
  ruleId?: string;
  unitIdHash?: string;
}

export interface ExperimentExposureReceipt {
  experimentId: string;
  variationId: string;
  featureId?: string;
  hashAttribute?: string;
  hashValue?: string;
}

function pseudonymize(value: unknown): string | undefined {
  const key = process.env.FEATURE_TELEMETRY_HASH_KEY;
  if (!key || typeof value !== "string" || !value) return undefined;

  return createHmac("sha256", key).update(value).digest("hex");
}

export function recordFeatureEvaluation(
  receipt: Omit<FeatureEvaluationReceipt, "unitIdHash">,
  unitId: unknown,
): void {
  console.info(
    "feature_evaluated",
    JSON.stringify({ ...receipt, unitIdHash: pseudonymize(unitId) }),
  );
}

export async function recordExperimentExposure(
  receipt: ExperimentExposureReceipt,
): Promise<void> {
  console.info("experiment_viewed", JSON.stringify(receipt));
}

import "server-only";

import { createGrowthbookAdapter } from "@flags-sdk/growthbook";
import { flag } from "flags/next";
import { after } from "next/server";
import { identify, type AppAttributes } from "./attributes";
import { recordExperimentExposure, recordFeatureEvaluation } from "./telemetry";

function requireServerEnvironment(name: "GROWTHBOOK_CLIENT_KEY"): string {
  const value = process.env[name];
  if (!value)
    throw new Error(`Missing required server environment variable: ${name}`);
  return value;
}

const growthbookAdapter = createGrowthbookAdapter({
  clientKey: requireServerEnvironment("GROWTHBOOK_CLIENT_KEY"),
  apiHost: process.env.GROWTHBOOK_API_HOST || "https://cdn.growthbook.io",
  clientOptions: {
    decryptionKey: process.env.GROWTHBOOK_DECRYPTION_KEY || undefined,
    onFeatureUsage: (featureKey, result, user) => {
      recordFeatureEvaluation(
        {
          featureKey,
          value:
            typeof result.value === "string" ||
            typeof result.value === "number" ||
            typeof result.value === "boolean" ||
            result.value === null
              ? result.value
              : JSON.stringify(result.value),
          source: result.source,
          ruleId: result.ruleId,
        },
        user.attributes.id,
      );
    },
  },
  initOptions: {
    timeout: 1_200,
    streaming: false,
  },
});

growthbookAdapter.setTrackingCallback((experiment, result) => {
  after(async () => {
    await recordExperimentExposure({
      experimentId: experiment.key,
      variationId: result.key,
      featureId: result.featureId,
      hashAttribute: result.hashAttribute,
      hashValue: result.hashValue,
    });
  });
});

export const newCheckoutFlowFlag = flag<boolean, AppAttributes>({
  key: "new-checkout-flow",
  description: "Use the new checkout flow",
  defaultValue: false,
  options: [false, true],
  identify,
  adapter: growthbookAdapter.feature<boolean>(),
});

"use client";

import { useState } from "react";

export function CheckoutClient({
  useNewFlow,
}: {
  useNewFlow: boolean;
}) {
  const [status, setStatus] = useState<"idle" | "submitting" | "complete">(
    "idle",
  );

  async function submit() {
    setStatus("submitting");
    // Replace this delay with the existing checkout mutation.
    await new Promise((resolve) => setTimeout(resolve, 100));
    setStatus("complete");
  }

  return (
    <section
      aria-labelledby="checkout-heading"
      data-new-checkout-flow={useNewFlow ? "on" : "off"}
    >
      <h1 id="checkout-heading">Checkout</h1>

      {useNewFlow ? (
        <div data-testid="new-checkout">
          <p>Review your address, delivery, and payment in one step.</p>
          <button type="button" onClick={submit} disabled={status === "submitting"}>
            {status === "submitting" ? "Submitting…" : "Place order"}
          </button>
        </div>
      ) : (
        <div data-testid="legacy-checkout">
          <p>Continue through the existing checkout steps.</p>
          <button type="button" onClick={submit} disabled={status === "submitting"}>
            {status === "submitting" ? "Submitting…" : "Continue"}
          </button>
        </div>
      )}

      <p role="status" aria-live="polite">
        {status === "complete" ? "Order submitted." : ""}
      </p>
    </section>
  );
}

import { CheckoutClient } from "./checkout-client";
import { newCheckoutFlowFlag } from "@/lib/feature-flags/flags";

export default async function CheckoutPage() {
  const useNewFlow = await newCheckoutFlowFlag();

  return <CheckoutClient useNewFlow={useNewFlow} />;
}

import { newCheckoutFlowFlag } from "@/lib/feature-flags/flags";

export async function GET() {
  const useNewFlow = await newCheckoutFlowFlag();

  return Response.json(
    {
      checkoutFlow: useNewFlow ? "new" : "legacy",
    },
    {
      headers: {
        "Cache-Control": "private, no-store",
      },
    },
  );
}

npm run dev

curl -sS -c /tmp/gb-cookies.txt http://localhost:3000/checkout > /tmp/checkout.html
curl -sS -b /tmp/gb-cookies.txt http://localhost:3000/api/checkout/config
grep -o 'data-new-checkout-flow="[^"]*"' /tmp/checkout.html

{"checkoutFlow":"legacy"}
data-new-checkout-flow="off"

import { growthbookAdapter } from "@flags-sdk/growthbook";

export const exampleFlag = flag({
  key: "example-flag",
  defaultValue: false,
  identify,
  adapter: growthbookAdapter.feature<boolean>(),
});

// Do not do this in a server module.
const gb = new GrowthBook();

export async function decideForUser(userId: string) {
  gb.setAttributes({ id: userId });
  return gb.isOn("new-checkout-flow");
}

npm install @growthbook/growthbook@1.7.0 @growthbook/growthbook-react@1.7.0

export interface AppFeatures {
  "new-checkout-flow": boolean;
  "client-checkout-help": boolean;
}

import "server-only";

import {
  GrowthBook,
  type Attributes,
  type FeatureApiResponse,
} from "@growthbook/growthbook";
import { after } from "next/server";
import type { AppFeatures } from "./app-features";
import { recordExperimentExposure, recordFeatureEvaluation } from "./telemetry";

const CACHE_TAG = "growthbook-features";
const apiHost = process.env.GROWTHBOOK_API_HOST || "https://cdn.growthbook.io";
const clientKey = process.env.GROWTHBOOK_CLIENT_KEY;

if (!clientKey) {
  throw new Error(
    "Missing required server environment variable: GROWTHBOOK_CLIENT_KEY",
  );
}

export async function loadGrowthBookPayload(): Promise<{
  payload: FeatureApiResponse;
  source: "next-cache-or-network" | "safe-fallback";
}> {
  try {
    const response = await fetch(`${apiHost}/api/features/${clientKey}`, {
      cache: "force-cache",
      next: {
        revalidate: 300,
        tags: [CACHE_TAG],
      },
      signal: AbortSignal.timeout(1_200),
    });

    if (!response.ok) {
      throw new Error(`GrowthBook payload returned HTTP ${response.status}`);
    }

    return {
      payload: (await response.json()) as FeatureApiResponse,
      source: "next-cache-or-network",
    };
  } catch (error) {
    console.error("growthbook_payload_fallback", {
      message: error instanceof Error ? error.message : String(error),
    });

    return {
      payload: { features: {} },
      source: "safe-fallback",
    };
  }
}

export async function createDirectServerGrowthBook(attributes: Attributes) {
  const { payload, source } = await loadGrowthBookPayload();

  const growthbook = new GrowthBook<AppFeatures>({
    attributes,
    decryptionKey: process.env.GROWTHBOOK_DECRYPTION_KEY || undefined,
    trackingCallback: (experiment, result) => {
      after(async () => {
        await recordExperimentExposure({
          experimentId: experiment.key,
          variationId: result.key,
          featureId: result.featureId,
          hashAttribute: result.hashAttribute,
          hashValue: result.hashValue,
        });
      });
    },
    onFeatureUsage: (featureKey, result) => {
      recordFeatureEvaluation(
        {
          featureKey,
          value:
            typeof result.value === "string" ||
            typeof result.value === "number" ||
            typeof result.value === "boolean" ||
            result.value === null
              ? result.value
              : JSON.stringify(result.value),
          source: result.source,
          ruleId: result.ruleId,
        },
        attributes.id,
      );
    },
  });

  await growthbook.init({ payload });

  return { growthbook, source };
}

"use client";

import {
  GrowthBook,
  GrowthBookProvider,
  type Attributes,
  type FeatureApiResponse,
} from "@growthbook/growthbook-react";
import { useEffect, useMemo, type PropsWithChildren } from "react";
import type { AppFeatures } from "./app-features";

declare global {
  interface Window {
    dataLayer?: Array<Record<string, unknown>>;
  }
}

export function DirectGrowthBookProvider({
  payload,
  attributes,
  children,
}: PropsWithChildren<{
  payload: FeatureApiResponse;
  attributes: Attributes;
}>) {
  const growthbook = useMemo(
    () =>
      new GrowthBook<AppFeatures>({
        attributes,
        trackingCallback: (experiment, result, user) => {
          window.dataLayer?.push({
            event: "experiment_viewed",
            experimentId: experiment.key,
            variationId: result.key,
            featureId: result.featureId,
            hashAttribute: result.hashAttribute,
            hashValue: result.hashValue,
            assignmentId: user?.attributes[result.hashAttribute],
          });
        },
      }).initSync({ payload }),
    [attributes, payload],
  );

  useEffect(() => () => growthbook.destroy(), [growthbook]);

  return (
    <GrowthBookProvider growthbook={growthbook}>
      {children}
    </GrowthBookProvider>
  );
}

"use client";

import { useFeatureIsOn } from "@growthbook/growthbook-react";
import type { AppFeatures } from "@/lib/feature-flags/app-features";

export function ClientCheckoutHelp() {
  const showHelp = useFeatureIsOn<AppFeatures>("client-checkout-help");

  if (!showHelp) return null;

  return (
    <aside aria-label="Checkout help">
      Need help? Contact support before placing the order.
    </aside>
  );
}

import { CheckoutClient } from "./checkout-client";
import { ClientCheckoutHelp } from "./client-checkout-help";
import { DirectGrowthBookProvider } from "@/lib/feature-flags/direct-provider";
import { createDirectServerGrowthBook } from "@/lib/feature-flags/direct-server";
import { getRequestAttributes } from "@/lib/feature-flags/attributes";

export default async function CheckoutPage() {
  const attributes = await getRequestAttributes();
  const { growthbook, source } =
    await createDirectServerGrowthBook(attributes);

  const useNewFlow = growthbook.isOn("new-checkout-flow");
  const payload = growthbook.getDecryptedPayload();
  growthbook.destroy();

  return (
    <div data-feature-payload-source={source}>
      <CheckoutClient useNewFlow={useNewFlow} />
      <DirectGrowthBookProvider payload={payload} attributes={attributes}>
        <ClientCheckoutHelp />
      </DirectGrowthBookProvider>
    </div>
  );
}

new-checkout-flow
  evaluation owner: server
  exposure event owner: server trackingCallback
  outcome identifier: anonymous_id

client-checkout-help
  evaluation owner: browser
  exposure event owner: browser trackingCallback
  outcome identifier: user_id

GROWTHBOOK_GLOBAL_CONFIG_CONNECTION_STRING="replace-with-vercel-connection-string"
GROWTHBOOK_GLOBAL_CONFIG_ITEM_KEY="replace-with-item-key"

import { createHmac, timingSafeEqual } from "node:crypto";
import { revalidateTag } from "next/cache";

export const runtime = "nodejs";

const CACHE_TAG = "growthbook-features";
const MAX_CLOCK_SKEW_SECONDS = 5 * 60;

function verifySignature(
  body: string,
  webhookId: string,
  timestamp: string,
  signatureHeader: string,
  secret: string,
): boolean {
  const timestampNumber = Number(timestamp);
  if (!Number.isFinite(timestampNumber)) return false;

  const age = Math.abs(Date.now() / 1000 - timestampNumber);
  if (age > MAX_CLOCK_SKEW_SECONDS) return false;

  const expectedBase64 = createHmac("sha256", secret)
    .update(`${webhookId}.${timestamp}.${body}`)
    .digest("base64");
  const expected = Buffer.from(expectedBase64);

  return signatureHeader.split(" ").some((versionedSignature) => {
    const [version, encoded] = versionedSignature.split(",", 2);
    if (version !== "v1" || !encoded) return false;

    const received = Buffer.from(encoded);
    return (
      received.length === expected.length && timingSafeEqual(received, expected)
    );
  });
}

export async function POST(request: Request) {
  const secret = process.env.GROWTHBOOK_WEBHOOK_SECRET;
  if (!secret) {
    console.error("growthbook_webhook_secret_missing");
    return new Response("Webhook unavailable", { status: 503 });
  }

  const webhookId = request.headers.get("webhook-id") || "";
  const timestamp = request.headers.get("webhook-timestamp") || "";
  const signature = request.headers.get("webhook-signature") || "";
  const body = await request.text();

  if (
    !webhookId ||
    !timestamp ||
    !signature ||
    !verifySignature(body, webhookId, timestamp, signature, secret)
  ) {
    return new Response("Invalid signature", { status: 401 });
  }

  // expire: 0 makes the next tagged read block for fresh data.
  revalidateTag(CACHE_TAG, { expire: 0 });

  console.info("growthbook_payload_cache_invalidated", { webhookId });
  return new Response(null, { status: 200 });
}

// src/lib/feature-flags/index.ts
export { newCheckoutFlowFlag } from "./flags";
export type { AppAttributes } from "./attributes";

growthbook.isOn("new-chekout-flow");
// Type error: "new-chekout-flow" is not a key of AppFeatures.

npm install --global growthbook@1.0.0
growthbook auth login
growthbook whoami
growthbook generate-types \
  --output ./src/lib/feature-flags/generated \
  --filename app-features.ts

src/lib/feature-flags/generated/app-features.ts

{
  "scripts": {
    "feature-types:generate": "growthbook generate-types --no-interactive --output ./src/lib/feature-flags/generated --filename app-features.ts",
    "feature-types:check": "npm run feature-types:generate && git diff --exit-code -- src/lib/feature-flags/generated/app-features.ts"
  }
}

grep -RhoE '(isOn|getFeatureValue|evalFeature)\("[A-Za-z0-9_-]+"' src \
  | sed -E 's/.*\("([A-Za-z0-9_-]+)"/\1/' \
  | sort -u

grep -R "new-checkout-flow" -n src tests

import { describe, expect, it } from "vitest";
import { buildGrowthBookAttributes } from "./attributes";

describe("buildGrowthBookAttributes", () => {
  it("uses a durable anonymous identity before login", () => {
    expect(buildGrowthBookAttributes("anon-123", null)).toEqual({
      id: "anon-123",
      anonymous_id: "anon-123",
      user_id: "",
      organization_id: "",
      employee: false,
      plan: "anonymous",
      identity_ready: true,
    });
  });

  it("uses trusted viewer fields after login", () => {
    expect(
      buildGrowthBookAttributes("anon-123", {
        userId: "user-456",
        organizationId: "org-789",
        plan: "pro",
        isEmployee: true,
      }),
    ).toEqual({
      id: "user-456",
      anonymous_id: "anon-123",
      user_id: "user-456",
      organization_id: "org-789",
      employee: true,
      plan: "pro",
      identity_ready: true,
    });
  });

  it("marks a missing identity as ineligible for rollout", () => {
    expect(buildGrowthBookAttributes(undefined, null)).toMatchObject({
      id: "missing-identity",
      identity_ready: false,
    });
  });
});

import {
  GrowthBookClient,
  type FeatureApiResponse,
} from "@flags-sdk/growthbook";
import { describe, expect, it } from "vitest";
import type { AppAttributes } from "./attributes";

interface TestFeatures {
  "new-checkout-flow": boolean;
}

const payload: FeatureApiResponse = {
  features: {
    "new-checkout-flow": {
      defaultValue: false,
      rules: [
        {
          id: "employee-rule",
          condition: { employee: true },
          force: true,
        },
        {
          id: "rollout-rule",
          condition: { identity_ready: true },
          force: true,
          coverage: 0.5,
          hashAttribute: "id",
        },
      ],
    },
  },
};

function attributes(
  id: string,
  overrides: Partial<AppAttributes> = {},
): AppAttributes {
  return {
    id,
    anonymous_id: id,
    user_id: "",
    organization_id: "",
    employee: false,
    plan: "anonymous",
    identity_ready: true,
    ...overrides,
  };
}

function evaluate(id: string, overrides: Partial<AppAttributes> = {}) {
  const growthbook = new GrowthBookClient<TestFeatures>().initSync({ payload });
  const value = growthbook.getFeatureValue("new-checkout-flow", false, {
    attributes: attributes(id, overrides),
  });
  growthbook.destroy();
  return value;
}

describe("new-checkout-flow fixture", () => {
  it("falls back for a missing identity", () => {
    expect(evaluate("missing-identity", { identity_ready: false })).toBe(false);
  });

  it("forces employees into the new path", () => {
    expect(evaluate("employee-1", { employee: true })).toBe(true);
  });

  it("is deterministic for the same identifier", () => {
    const first = evaluate("stable-user-1");
    expect(evaluate("stable-user-1")).toBe(first);
    expect(evaluate("stable-user-1")).toBe(first);
  });

  it("places a population on both sides of a 50% rollout", () => {
    const values = new Set(
      Array.from({ length: 200 }, (_, index) => evaluate(`user-${index}`)),
    );
    expect(values).toEqual(new Set([true, false]));
  });

  it("uses the code fallback for an unknown feature", () => {
    const growthbook = new GrowthBookClient();
    growthbook.initSync({ payload: { features: {} } });
    expect(
      growthbook.getFeatureValue("new-checkout-flow", false, {
        attributes: attributes("user-1"),
      }),
    ).toBe(false);
    growthbook.destroy();
  });
});

import { expect, test } from "@playwright/test";

test("checkout page and API use the same stable assignment", async ({
  context,
  page,
}) => {
  await page.goto("/checkout");

  const root = page.locator("[data-new-checkout-flow]");
  const pageValue = await root.getAttribute("data-new-checkout-flow");
  expect(["on", "off"]).toContain(pageValue);

  const cookies = await context.cookies();
  const anonymousCookie = cookies.find(
    (cookie) => cookie.name === "gb_anon_id",
  );
  expect(anonymousCookie?.value).toBeTruthy();

  const response = await context.request.get("/api/checkout/config");
  expect(response.ok()).toBeTruthy();
  const body = (await response.json()) as { checkoutFlow: "new" | "legacy" };

  expect(body.checkoutFlow === "new" ? "on" : "off").toBe(pageValue);

  await page.reload();
  await expect(root).toHaveAttribute("data-new-checkout-flow", pageValue!);
});

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:e2e": "playwright test",
    "build": "next build"
  }
}

npm run typecheck
npm test
npm run build
npm run test:e2e

typecheck: exit 0
unit tests: all passed
next build: exit 0
Playwright parity test: passed

timestamp
feature_key
value
source
rule_id
deployment_environment
application_version
unit_id_hash (optional)

timestamp
experiment_id
variation_id
feature_id
hash_attribute
assignment identifier or approved pseudonym
experiment phase when present

curl -sS -c /tmp/gb-cookies.txt http://localhost:3000/checkout > /dev/null

feature_evaluated {"featureKey":"new-checkout-flow","value":false,"source":"defaultValue",...}

SELECT
  experiment_id,
  variation_id,
  COUNT(*) AS exposures,
  COUNT(DISTINCT assignment_id) AS units
FROM experiment_exposures
WHERE timestamp >= CURRENT_TIMESTAMP - INTERVAL '1 hour'
  AND experiment_id = 'new-checkout-flow'
GROUP BY 1, 2
ORDER BY 1, 2;

if (await adminDashboardFlag()) {
  return readAllCustomerData();
}

await requirePermission("customer-data:read");

if (await newCustomerDataViewFlag()) {
  return readCustomerDataWithNewView();
}

return readCustomerDataWithLegacyView();

Feature: new-checkout-flow
Owner: Checkout team
Incident owner: On-call engineer
Randomization unit: organization_id
Safe code fallback: false -> legacy checkout
Primary health signals: checkout API error rate, payment authorization failure rate
User signal: completed checkout / started checkout
Rollback authority: On-call engineer may force false without product approval
Maximum propagation objective: 5 minutes
Cleanup issue: CHECKOUT-1234
Cleanup deadline: 14 days after 100% and rollback-window approval

Conditions: identity_ready = true
Hash attribute: organization_id
Serve value: true
Coverage: 1%

1% -> 5% -> 25% -> 50% -> 100%

export async function shouldUseNewCheckout(): Promise<boolean> {
  if (process.env.FORCE_LEGACY_CHECKOUT === "true") {
    console.warn("feature_emergency_override", {
      featureKey: "new-checkout-flow",
      value: false,
    });
    return false;
  }

  return newCheckoutFlowFlag();
}

if statement
-> environment-specific value
-> runtime mutation
-> authenticated admin endpoint
-> per-user or per-account targeting
-> deterministic percentage hashing
-> cache and invalidation
-> change history and review
-> experiment exposure events
-> result analysis
-> stale-flag inventory and cleanup

Owner: Checkout team
Expected lifetime: 30 days
Removal condition: 100% for 14 days, no rollback, health thresholds met
Removal issue: CHECKOUT-1234
Legacy code owner: Checkout team
Data migration dependency: none / link

grep -R "new-checkout-flow\|newCheckoutFlowFlag\|legacy-checkout" -n src tests

# no matches

npm run feature-types:check
npm run typecheck
npm test
npm run build
npm run test:e2e

1. Known internal identity -> page on, API new
2. Known control identity -> page off, API legacy
3. Forced rollback -> both identities page off, API legacy

guide: nextjs-app-router-production-feature-flags
verified_at: 2026-08-12
growthbook_commit: e44a15af063860c7118f52508746356d55e5a91d
depends_on:
  - docs/docs/lib/nextjs.mdx
  - docs/docs/lib/js.mdx
  - docs/docs/lib/react.mdx
  - docs/docs/features/basics.mdx
  - docs/docs/features/rules.mdx
  - docs/docs/features/targeting.mdx
  - docs/docs/features/environments.mdx
  - docs/docs/features/diagnostics.mdx
  - docs/docs/webhooks/sdk-webhooks.mdx
  - packages/sdk-js/src/**
  - packages/sdk-js/test/**
  - packages/sdk-react/src/**
  - packages/sdk-react/test/**
  - vercel/flags/packages/adapter-growthbook/**
volatile:
  - Next.js request APIs, Proxy, Data Cache, and revalidation behavior
  - @flags-sdk/growthbook export names and config-store variables
  - GrowthBook JavaScript and React SDK initialization and tracking APIs
  - GrowthBook CLI type-generation syntax
  - Cloud and self-hosted plan availability
  - Vercel Global Config integration and limits
verification:
  - type generation diff
  - TypeScript compile
  - unit tests with fixed payload
  - production Next.js build
  - Playwright identity and page/API parity
  - signed webhook or config-store update receipt when configured
  - staging rollout and rollback drill
  - experiment exposure readback from the destination data source