Experiments
Feature Flags
AI

How companies are safely building AI-assisted features

A graphic of a bar chart with an arrow pointing upward.

AI-assisted features rarely fail like normal product changes. A button experiment can lose a few points of conversion and still be easy to understand. An AI support summary, recommendation system, search assistant, or code generation workflow can look healthy in aggregate while producing slow responses, low-quality answers, or confusing edge cases for specific users.

That is why the best AI feature flag best practices are less about hiding unfinished work and more about controlling live behavior. The flag becomes the release control for model selection, prompt versions, retrieval settings, fallback paths, and audience exposure. It gives product, engineering, and data teams a way to move quickly without treating every AI change as a full-production bet.

This guide lays out the practical system companies are using to build AI-assisted features safely: define the controllable configuration, expose it gradually, measure both product value and AI quality, and keep a rollback path ready before the first external user sees the feature.

Why AI-assisted features need runtime controls

Traditional release processes assume that the riskiest change is the code deployment. AI-assisted features break that assumption. The behavior users experience may change because of a new model, a revised system prompt, a retrieval setting, a moderation threshold, a context window change, or a provider-side update.

Some of those changes happen without a code deploy. A prompt can be edited in a dashboard. A model ID can move from one version to another. A retrieval strategy can change which documents are sent to the model. Your CI pipeline may still be green while the user-facing behavior has moved.

That is the operational gap. A team needs a control plane that treats AI behavior as production behavior even when the application code is unchanged. Feature flags are useful here because they decouple deployment from release. Code can ship dark, an AI path can stay off by default, and exposure can expand only after the team sees real evidence.

The safety goal is not to remove production learning. For AI systems, production is where the long tail appears. The goal is to make that learning controlled. The Google SRE Workbook chapter on canarying releases frames the release problem around exposing changes to a small portion of real traffic before broad rollout. AI-assisted features need the same discipline, but at the application and configuration layer rather than only at the infrastructure layer.

The NIST AI Risk Management Framework uses Govern, Map, Measure, and Manage as the core functions for AI risk. That is a useful mental model for release work too. Govern the change before launch, map who could be affected, measure live behavior, and manage rollback or expansion based on evidence.

Put the full AI behavior behind the flag

The first mistake teams make is flagging only the on/off state of the AI feature. That helps with visibility, but it misses the actual source of change. The safer pattern is to put the AI configuration behind the flag as a structured payload.

A simple boolean flag can answer, "Should the AI summary feature appear?" A JSON flag can answer a more useful question: "Which model, prompt version, sampling settings, fallback, and guardrail mode should this user receive?"

That distinction matters because model behavior is an interaction effect. A lower temperature may be appropriate for one prompt and too rigid for another. A better model may need a different token budget. A retrieval change may improve accuracy for technical users while creating confusing answers for new users. If each setting is controlled separately, it becomes harder to know which configuration a user actually experienced.

A single JSON payload keeps the variant legible:

{
  "model": "gpt-4.1-mini",
  "promptVersion": "support-summary-v3",
  "temperature": 0.2,
  "fallback": "rules_based_summary",
  "maxOutputTokens": 450
}

This is the configuration the application reads at request time. The user does not need to know which version they received, but the team does. That matters for debugging, experiment analysis, cost tracking, and incident response.

GrowthBook's feature flag documentation describes the core pattern: control application behavior without deploying new code, target specific users, roll out gradually, or run experiments. For AI-assisted features, that same pattern becomes the boundary between deployment and exposure.

OpenFeature's evaluation context specification is another useful reference point. The evaluation context carries the user, account, environment, or request attributes that determine how a flag resolves. AI rollouts depend on that context because the safe first audience is rarely "a random 10% of everyone." It is often employees, then beta users, then a specific plan tier, then a wider percentage of production.

Roll out by risk, not enthusiasm

The strongest rollout plans sequence exposure by risk. Start with users who can tolerate rough edges and generate useful feedback. Expand only when the data says the feature is stable enough for the next audience.

That is different from a launch plan built around enthusiasm. A team may feel excited about a new AI feature because the demo worked, the internal eval looked good, and the product narrative is strong. None of that proves the feature is ready for broad production exposure.

Use a staged rollout plan that makes each step explicit:

StageAudienceDecision signal
InternalEmployees and test accountsBasic functionality, logging, latency, and fallback behavior work
BetaOpted-in users or design partnersOutput quality is acceptable on real tasks and obvious edge cases are contained
Limited productionA small percentage or one lower-risk segmentGuardrail metrics stay within agreed thresholds
Broader productionMore segments and higher trafficProduct outcomes improve without harming quality, cost, or trust signals
Full releaseGeneral availabilityOwners have a cleanup plan, monitoring, and documented rollback criteria

The exact percentages matter less than the discipline behind the gates. Before increasing exposure, define what would stop the rollout. Error rate, p95 latency, hallucination reports, correction rate, support contact rate, cost per successful task, and downstream conversion can all be valid stop signals depending on the feature.

GrowthBook feature rules support forced values, percentage rollouts, experiments, and Safe Rollouts. That lets teams combine audience targeting with progressive exposure. You can give employees a forced value, open a percentage rollout to beta users, then graduate the same feature into an experiment when you need stronger evidence.

For teams that want automated guardrails, Safe Rollouts release a feature to a subset of users while monitoring metrics for regressions. That is especially useful for AI-assisted features because the first problem may not be a crash. It may be a slow quality drift that appears as worse task completion, higher retry behavior, or lower conversion after the AI interaction.

The community pain point is real too. Practitioner threads on Hacker News and Reddit keep returning to the same tradeoff: flags reduce release risk, but they also create operational debt if teams do not own cleanup, naming, and lifecycle rules. AI features make that lifecycle discipline even more important because stale AI configurations can become hidden production behavior.

Measure the quality of the AI path, not just usage

AI-assisted features can win on a shallow metric while harming the product. A summarizer may increase clicks because users are curious, but lower retention because the summaries are unreliable. A recommendation model may raise engagement while making costly calls to an expensive provider. A support assistant may reduce ticket creation while increasing user frustration if people stop asking for help altogether.

The measurement plan needs at least three layers.

First, measure the product outcome. Did the user complete the task faster? Did activation improve? Did the feature reduce manual work? Did it improve conversion, retention, or engagement in a way the business actually values?

Second, measure AI quality. Track user correction behavior, thumbs-up or thumbs-down feedback, retry rate, refusal rate, escalation rate, and human review outcomes where they exist. For generative features, sample output quality directly. The OpenAI evaluation best practices guide is a useful reminder that eval design has to reflect the task and failure modes you care about, not a generic benchmark.

Third, measure operational guardrails. Track latency, timeout rate, provider error rate, cost per request, cost per successful task, and fallback usage. A model that creates better answers at five times the cost may still be the right choice for a high-value enterprise workflow, but the team should make that tradeoff consciously.

This is where feature flag experiments matter. A staged rollout asks, "Can this safely expand?" A controlled experiment asks, "Is this actually better?" AI-assisted features usually need both. The canary catches breakage; the experiment supports the promotion decision.

The OpenFeature flag evaluation specification separates flag evaluation from any specific vendor control plane. That is useful conceptually because it reminds teams to instrument the actual evaluated variant. The analysis should know not only that the user saw "AI enabled," but which model configuration, prompt version, and rollout rule produced the experience.

Build fallback behavior before launch

A fallback is not a vague promise to turn the feature off. It is the user experience that appears when the AI path is disabled, unhealthy, or outside the user's cohort.

For a support summary, the fallback might be a deterministic rules-based summary or the original ticket view. For AI search, it might be keyword search. For an AI recommendation module, it might be the previous ranking algorithm. For a writing assistant, it might be a blank editor with templates.

The fallback should be boring. That is a compliment. During an incident, boring is what protects user trust.

This is also where flag defaults matter. If your application evaluates an AI config flag and receives no active rule, it should have a known-good default. The default should be versioned in code, tested, and observable. The fallback path should emit analytics too, because a spike in fallback usage is itself a signal that something is wrong.

External best-practice guidance lines up with this. Unleash's feature flag best practices emphasize short-lived flags, naming conventions, server-side evaluation for sensitive flags, and lifecycle management. Those are not just hygiene rules. For AI-assisted features, they prevent hidden prompt versions, half-retired model routes, and forgotten kill switches from becoming the production system nobody remembers approving.

Where GrowthBook fits in the workflow

GrowthBook should not be introduced as magic AI safety. The useful framing is more practical: GrowthBook gives the team one place to control rollout state, target audiences, run experiments, and connect the result back to product metrics.

For engineering teams, GrowthBook's AI-native development platform and MCP server make it possible for AI agents to work inside existing release controls. Agents can help create flags, inspect flags, or draft experiment specs, but the same review and approval expectations should apply. Speed from AI coding tools is only useful if the shipped change still passes through a controlled release process.

For product and data teams, GrowthBook connects AI feature rollouts to experimentation. A team can start with an internal flag, expand to a percentage rollout, add guardrail metrics, and then run an experiment to compare configurations. The same feature that limits blast radius can become the assignment mechanism for the test.

For governance, the important point is ownership. Every AI-assisted feature needs a named owner, a fallback, a metric plan, and cleanup criteria. Flags make those controls possible, but the team still has to operate them.

GrowthBook has already covered the deeper model-rollout pattern in feature flagging for AI models. The additional point here is broader: companies are not only flagging model swaps. They are flagging the whole AI-assisted workflow, including prompt versions, fallback states, audience gates, and the metrics that decide whether a feature deserves more exposure.

What to do next

Start with one AI-assisted workflow that is close enough to production to matter but small enough to control. Do not begin with the most complex agent in the product. Pick a summarizer, recommendation widget, search enhancement, or internal assistant where the fallback is obvious.

Then define the release contract:

  • What configuration will the flag control?
  • Which audience sees it first?
  • What fallback appears when the flag is off?
  • Which metrics must not get worse?
  • Who can approve expansion?
  • When will the flag or old variant be cleaned up?

If those questions feel bureaucratic, that is the point at which the team is most likely to need them. AI-assisted features compress the distance between an idea, a generated implementation, and live user behavior. The companies that ship them safely are not moving slowly. They are making the release path explicit enough that speed does not become uncontrolled exposure.

Feature flags are the starting point, not the entire safety system. Pair them with staged rollouts, evals, guardrails, fallback behavior, and experiment analysis. That stack gives teams a way to learn from real users while keeping the blast radius small enough to act when the learning is uncomfortable.

Table of Contents

Related Articles

See All Articles
Feature Flags
Experiments

Add local feature flags to a React app with TypeScript

Nov 20, 2026
x
min read

A magazine's home page shows two recent issues. The design team wants subscribers to try a shelf with four. All four covers are public, and changing editions while the page is open should update the shelf immediately. That gives you a small React feature with a useful acceptance test. Click from guest to subscriber and back, and count the covers each time.

We'll put the display limit in a typed local flag, evaluate it inside a React component, and leave the choice of edition with the app. The example runs in a client-rendered React app without a GrowthBook account, an SDK key, or a request for flag rules. For the wider workflow, free feature flags for coding agents explains what to ask an agent to implement and how to review the result.

Define what one flag controls

Start with an existing React and TypeScript app, or create a Vite React project for the example. Install both GrowthBook packages so the definitions and the hooks resolve against compatible SDK versions.

npm create vite@latest issue-shelf -- --template react-ts
cd issue-shelf
npm install
npm install @growthbook/growthbook@^2.2.0 @growthbook/growthbook-react@^2.2.0

Create src/flags.ts. Here the feature value is a number, which lets the component use the same rendering code for either edition. A future change from four covers to three is one edit to the rule.

import type { LocalFeatures } from "@growthbook/growthbook";

export type Edition = "guest" | "subscriber";
type Features = { issueLimit: number };
type Attributes = { id: string; edition: Edition };

declare module "@growthbook/growthbook" {
  interface Register {
    features: Features;
    attributes: Attributes;
  }
}

export const features: LocalFeatures = {
  issueLimit: {
    defaultValue: 2,
    rules: [
      { condition: { edition: "subscriber" }, force: 4 },
    ],
  },
};

A guest falls through to the default of two. A subscriber matches the rule and gets four. This rule applies to every subscriber, so the ID has no effect on the result here. If you later roll the shelf out to a percentage of subscribers, you already have an identity to use for repeatable assignment.

The type registration release note explains the version requirement for LocalFeatures. The registration connects the definition, the attributes, and the value returned by the hook. For the TypeScript mechanics, see Jeremy Dorn's Register pattern walkthrough.

Put the current reader above the shelf

Replace src/App.tsx with the component below. The edition switch is a local fixture so anyone reviewing the change can reproduce both states. In an existing app, take those two values from the active reader in your session layer.

import { useMemo, useState } from "react";
import { GrowthBook, GrowthBookProvider } from "@growthbook/growthbook-react";
import { features, type Edition } from "./flags";
import { IssueShelf } from "./IssueShelf";

export default function App() {
  const readerId = "reader-17";
  const [edition, setEdition] = useState<Edition>("guest");

  const gb = useMemo(() => new GrowthBook({
    attributes: { id: readerId, edition },
    defaultHashVersion: 2,
  }).initSync({ payload: { features } }), [readerId, edition]);

  return (
    <GrowthBookProvider growthbook={gb}>
      <main>
        <h1>Recent issues</h1>
        <p>Current edition: {edition}</p>
        <button onClick={() => setEdition(
          edition === "guest" ? "subscriber" : "guest"
        )}>
          Switch edition
        </button>
        <IssueShelf />
      </main>
    </GrowthBookProvider>
  );
}

The provider receives an instance initialized with the current reader and the checked-in rules. React can render the correct shelf on the first pass for that reader. If the app is still loading a session, decide what should occupy the shelf in the meantime. For this public list a two-cover guest view is reasonable. On a page where a switch would interrupt the reader, wait for the session before mounting the shelf.

Give your agent the React setup

Use the local flags guide to ask for a typed definition, a provider with the current reader, and a test that changes the edition.

Open the Agent Guide

The useMemo dependencies include the ID and the edition. If a reader subscribes while signed in, their ID can stay the same while their edition changes. Depending only on the ID would leave the old SDK instance in place. Passing a fresh object as the dependency on every render would create unnecessary instances. The example uses the two primitive values the rule setup actually needs.

Read the numeric flag where React renders the list

Create src/IssueShelf.tsx. Keep one stable ID per issue and let the component use the resolved value to select how many items to render.

import { useFeatureValue } from "@growthbook/growthbook-react";

const issues = [
  { id: "nov", title: "November · Print shops" },
  { id: "oct", title: "October · Bookbinders" },
  { id: "sep", title: "September · Type designers" },
  { id: "aug", title: "August · Paper mills" },
];

export function IssueShelf() {
  const limit = useFeatureValue("issueLimit", 2);

  return (
    <ul aria-label="Recent magazine issues">
      {issues.slice(0, limit).map(issue => (
        <li key={issue.id}>{issue.title}</li>
      ))}
    </ul>
  );
}

Keep the hook at the top of the component, inside the provider's subtree. The React SDK supplies the flag value through that provider. Calling a hook inside a click handler or inside the list loop would break the Rules of Hooks. Use the returned number in ordinary render logic.

There are two places you can see the number two in this implementation. The definition's defaultValue is what an ordinary guest gets through evaluation. The 2 passed to the hook is a fallback for a value the SDK can't supply. Giving them the same value makes the basic shelf a sensible fallback, but checking only the guest case would let a broken provider arrangement or missing definition go unnoticed. The subscriber case proves that the component actually received the rule.

The list keys identify magazine issues. Keep those keys independent of the flag. Switching from two covers to four should preserve the identity of the first two rows. There's also no need to remount the whole app with an edition-specific key. React preserves state according to component position and keys. For example, a search input outside the shelf shouldn't lose its text because someone subscribed.

Check the transition in both directions

Use the template's build script to type-check and bundle the app. Once that passes, start the dev server and open the local address it prints.

npm run build
npm run dev

On first load, the page says guest and lists November and October. Click Switch edition. The same page should say subscriber and add September and August. Click again. The list should return to the original two issues, in order. This last check catches code that appends more results on upgrade and never removes them on downgrade.

For a compile-time check, temporarily replace the numeric fallback with the string "2". Run the build again and inspect the error on the hook call. Then restore 2 and rebuild. If the string compiles, check that src/flags.ts belongs to the same TypeScript project as the component and that the package manager resolved compatible core and React versions.

npm ls @growthbook/growthbook @growthbook/growthbook-react

Look for the core package used by your app and by the wrapper. If the app has several incompatible installations, align the versions before diagnosing the JSX. A team using an existing build script should also confirm it actually runs the TypeScript checker.

Hand off a React change someone can review

Give your coding agent the one-shot local feature flags guide and a short description of the observable behavior. For this shelf, the request can be as specific as the test.

Show two public issues to guests and four to subscribers.
Keep the same reader ID when switching editions in the test.
Report the initial titles, the titles after upgrading, and the titles
after switching back. Include the type-check command you ran.

The shelf controls how many public titles to display. If your actual feature unlocks paid articles, enforce access when the server serves an article. A client-rendered flag only decides what to show in that browser. Whenever a change to the display limit can wait for a deployment, the small local file keeps the decision reviewable alongside the component. When an editor needs to change it between issues without an engineering release, that's the point to consider managed rules.

Manage the shelf in GrowthBook

Start a GrowthBook workspace when your magazine team is ready to manage shelf rules between deployments.

Get Started with GrowthBook
Feature Flags
Experiments

Use local feature flags per request in Node.js

Nov 20, 2026
x
min read

Two customers download the same weekly report. One has agreed to preview a new CSV column. The other feeds the old two-column format into an importer. Both requests can land on the same Node.js process, and each needs the right file even if the other request arrives while the report is loading.

This tutorial builds that endpoint with one checked-in feature flag. The process loads the rules once. Each request supplies its own workspace attributes and receives its own evaluation. You can run the whole example on your machine without an account, a client key, or a flag server. The free feature flags for coding agents walkthrough introduces the local approach. Here we'll give the agent a server-specific test to pass.

Set up a small TypeScript service

Use Node.js 22 or newer for this example. In an empty directory, create an npm project that uses ES modules, install the core SDK, and add the TypeScript tools.

npm init -y
npm pkg set type=module
npm install @growthbook/growthbook@^2.2.0
npm install -D typescript tsx @types/node@22

Create tsconfig.json at the project root. The sample runs TypeScript directly with tsx and checks types in a separate step. Type checking with tsx explains why the two commands serve different purposes.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["*.ts"]
}

The following files all live next to that configuration. The server imports ./flags.js even though the source file is flags.ts. That spelling follows TypeScript's Node.js module resolution for ESM and works with this runner.

Define the report contract in one flag

Create flags.ts. The public format has two columns. The sample preview workspace gets one additional column. The only targeting attribute the rule needs today is reportPreview. Carry the workspace ID too, so two people downloading a report on behalf of the same workspace can share an assignment if you introduce a percentage rollout later.

import type { LocalFeatures } from "@growthbook/growthbook";

type Features = { includeUniqueReaders: boolean };
export type Workspace = { workspaceId: string; reportPreview: boolean };

declare module "@growthbook/growthbook" {
  interface Register {
    features: Features;
    attributes: Workspace;
  }
}

export const features: LocalFeatures = {
  includeUniqueReaders: {
    defaultValue: false,
    rules: [{ condition: { reportPreview: true }, force: true }],
  },
};

The SDK type registration update covers this rule syntax and the 2.2.0 minimum. If you misspell reportPreview in a condition or use a string where the boolean flag expects a value, TypeScript can point at the definition. The Register pattern also makes the same feature name available in other modules without threading a generic type through each handler.

Before you add the endpoint, decide what belongs to the process and what belongs to the request. The feature definitions are identical for both customers. Their identity and preview enrollment can differ. If a handler changes an attribute on a single shared user instance before awaiting a database query, another handler could replace that attribute before the first handler resumes.

Give your agent a server-side task

Use the one-shot guide to add checked-in rules. Ask your agent to keep workspace attributes local to each request and demonstrate both CSV formats.

Open the Local Flags Guide

Create a scope when the request arrives

Create server.ts. The Node.js SDK provides GrowthBookClient for the process and createScopedInstance for the current request. The two fixture paths below stand in for two authenticated workspaces. The server binds to the loopback address so you can exercise it locally.

import { createServer } from "node:http";
import { setTimeout as delay } from "node:timers/promises";
import { GrowthBookClient } from "@growthbook/growthbook";
import { features, type Workspace } from "./flags.js";

const client = new GrowthBookClient({ defaultHashVersion: 2 })
  .initSync({ payload: { features } });

const demos = new Map<string, Workspace>([
  ["/demo/preview", { workspaceId: "press-a", reportPreview: true }],
  ["/demo/standard", { workspaceId: "press-b", reportPreview: false }],
]);

createServer(async (req, res) => {
  const workspace = demos.get(req.url ?? "");
  if (req.method !== "GET" || !workspace) {
    res.writeHead(404).end();
    return;
  }

  const gb = client.createScopedInstance({ attributes: workspace });
  await delay(10); // Stand-in for loading this workspace's report.
  const expanded = gb.isOn("includeUniqueReaders");
  const csv = expanded
    ? "period,downloads,unique_readers\nweek-1,80,55\n"
    : "period,downloads\nweek-1,80\n";

  res.writeHead(200, {
    "Content-Type": "text/csv; charset=utf-8",
    "Cache-Control": "private, no-store",
  });
  res.end(csv);
}).listen(4178, "127.0.0.1", () => {
  console.log("Report server listening on http://127.0.0.1:4178");
});

The HTTP handler looks up a workspace, creates its scope, and holds that scope across an asynchronous operation. The short promise-based timer gives a second request time to arrive. In a real export, that's where the database or storage read would happen. Keep the stable client at module scope and the scoped instance inside the handler. If a formatter needs the decision, pass it the boolean or the scoped instance.

In production, resolve the workspace and its access rights from the authenticated session before reading the report. The two selectable paths here are fixtures for public sample data. A caller's choice of a header, query string, or workspace slug can't establish permission to read another customer's report. The endpoint also prevents shared response caching. If you cache real exports, the cache needs to distinguish the workspace and the report format, along with any other inputs that change the response.

Test two requests that overlap

In the first terminal, type-check the service and start it. A successful type check exits quietly. The next command prints the loopback address and keeps the server running.

npx tsc --noEmit
npx tsx server.ts

Save the following as verify.mjs. In a second terminal, run node verify.mjs. Node's built-in fetch calls the local server. Strict assertions compare the full header and data row, including where each row ends.

import assert from "node:assert/strict";

async function report(name) {
  const response = await fetch("http://127.0.0.1:4178/demo/" + name);
  assert.equal(response.status, 200);
  return response.text();
}

const [preview, standard, previewAgain] = await Promise.all([
  report("preview"), report("standard"), report("preview"),
]);

assert.equal(preview, "period,downloads,unique_readers\nweek-1,80,55\n");
assert.equal(standard, "period,downloads\nweek-1,80\n");
assert.equal(previewAgain, preview);
console.log("Both workspaces received the expected CSV.");

You should see the single success line. Testing just the preview workspace proves that the code can add a column. Testing both responses catches the more expensive mistake of silently changing an existing customer's export. Keeping the old format assertion around is especially valuable when the downstream importer belongs to someone outside your team.

To check the compile-time boundary, temporarily change gb.isOn("includeUniqueReaders") to gb.isOn("includeUniqueReader") and rerun npx tsc --noEmit. The diagnostic should identify the misspelled key. Restore it before running the server again. A coding agent can include the before-and-after type check and the two CSV headers in its pull request.

Decide when to expand the report

When one preview customer is ready, leave everyone else on the default. If the next step is to enroll a fraction of workspaces, choose an attribute that matches the promise you're making. Hashing a workspace ID lets colleagues downloading the same report share a format. Hashing each user's ID could give two analysts in the same company different column sets. The one-shot guide shows how to express a percentage and hash attribute in a local rule.

A new rule in flags.ts reaches a process through your deployment. During a rolling deploy, the same workspace might hit old and new processes. If customers need a durable choice of export schema, keep supporting the agreed format in the API itself. When the operational requirement is to change targeting between deploys, you can keep the scoped evaluation in the handler and change how the process receives its rules.

Manage report targeting in Cloud

Create a GrowthBook workspace when the team supporting exports needs to expand the preview independently of a server release.

Get Started with GrowthBook
Feature Flags
Experiments

Use local feature flags in the Next.js App Router

Nov 20, 2026
x
min read

Your conference agenda has a new “Show room” button. Reviewers should see it on the first page load. Everyone else should get the existing agenda. If a Server Component renders the old agenda and a browser hook independently decides to show the new button, the first HTML and the browser can disagree.

In the Next.js App Router, the server can make this decision once and pass a boolean to the interactive component. We'll define the flag in the repo, select the preview audience with a local test cookie, and verify the actual HTML for both visitors. Clicking the button will still work after hydration. You can follow along without a GrowthBook account or client key. If you're assigning this work to an agent, the free feature flags for coding agents walkthrough gives the background.

Keep the flag definitions on the server

Use a TypeScript App Router project, or create a small one with create-next-app. These paths assume the project has an app directory at its root. If yours uses src/app, put both app and lib under src so the relative imports still match.

npx create-next-app@latest agenda-flags --ts --app --empty --use-npm --no-src-dir --no-tailwind --yes
cd agenda-flags
npm install @growthbook/growthbook@^2.2.0 server-only

Keep the starter's root layout. Create lib/agenda-flags.ts with the following code. The SDK type registration update explains how LocalFeatures checks the flag and its rule against the registered types. This setup requires version 2.2.0 or later.

import "server-only";
import { GrowthBookClient, type LocalFeatures } from "@growthbook/growthbook";

type Features = { agendaRoomDetails: boolean };
type Attributes = { audience: "preview" | "public" };

declare module "@growthbook/growthbook" {
  interface Register {
    features: Features;
    attributes: Attributes;
  }
}

const features: LocalFeatures = {
  agendaRoomDetails: {
    defaultValue: false,
    rules: [{ condition: { audience: "preview" }, force: true }],
  },
};

const client = new GrowthBookClient({ defaultHashVersion: 2 })
  .initSync({ payload: { features } });

export function showRoomDetails(audience: Attributes["audience"]) {
  const gb = client.createScopedInstance({ attributes: { audience } });
  return gb.isOn("agendaRoomDetails");
}

The module can reuse the client and rules across requests handled by the same process. It only holds the current visitor's audience inside the function call. Two requests can therefore use the same flag file and get different results. The Node.js SDK documents the scoped client used under the App Router here.

This particular rule has no percentage and needs no visitor ID. The two audiences are sufficient. If the team later asks for a rollout to 10% of attendees, add a stable attendee or registration ID and choose which of those units should stay together. Jeremy Dorn's Register pattern article explains how a change to an attribute type reaches the call sites that construct it.

Read the cookie for this request

Create app/agenda/page.tsx. The static heading can render for everyone. The request-specific content sits behind a Suspense boundary, so the fallback can show a neutral loading message until the server has the cookie.

import { Suspense } from "react";
import { cookies } from "next/headers";
import { showRoomDetails } from "../../lib/agenda-flags";
import { Agenda } from "./Agenda";

async function AgendaForVisitor() {
  const jar = await cookies();
  const audience = jar.get("agenda-preview")?.value === "1"
    ? "preview"
    : "public";

  return <Agenda showRoom={showRoomDetails(audience)} />;
}

export default function AgendaPage() {
  return (
    <main>
      <h1>Conference agenda</h1>
      <Suspense fallback={<p>Loading the agenda…</p>}>
        <AgendaForVisitor />
      </Suspense>
    </main>
  );
}

The App Router's cookies function reads the incoming request asynchronously. Read it inside the visitor-specific component. Keeping that read out of shared cached code lets the surrounding page reuse common content without treating one visitor's decision as another's. This placement also accommodates App Router projects using Cache Components.

Give your agent the Next.js setup

Use the local flags guide with a concrete request to evaluate one flag on the server and return the same decision to the browser.

Open the Local Flags Guide

The cookie in this demo is a convenient way to preview a public UI treatment. Anyone with that cookie can see the room label. To target paying attendees or private sessions, obtain the audience from the verified session on the server and authorize the underlying data separately.

Pass one decision to the interactive component

Create app/agenda/Agenda.tsx. It's a Client Component because a visitor can open and close the room details. Its initial branch comes directly from the boolean supplied by the page.

"use client";

import { useState } from "react";

export function Agenda({ showRoom }: { showRoom: boolean }) {
  const [open, setOpen] = useState(false);

  return (
    <section data-agenda={showRoom ? "preview" : "standard"}>
      <h2>10:00 · Designing for print</h2>
      {showRoom && (
        <>
          <button aria-expanded={open} onClick={() => setOpen(!open)}>
            {open ? "Hide room" : "Show room"}
          </button>
          {open && <p>Room 204</p>}
        </>
      )}
    </section>
  );
}

The client boundary takes a serializable prop. The component receives true or false. The SDK instance, targeting rules, and cookie handling stay in the server module. You don't need a React provider for this component because its only browser-side choice is whether the visitor has clicked the button.

Follow one page load through server rendering and hydration. For a preview visitor, the server can send a section with a “Show room” button. React's first client render gets the same showRoom value and starts with open set to false. Hydration attaches the click handler. Opening the room detail then updates component state and doesn't require another flag evaluation.

Verify the HTML and the click separately

Build the production app and start it on port 3100.

npm run build
npm run start -- -p 3100

In a second terminal, save this as verify-agenda.mjs in the project root and run node verify-agenda.mjs. The test makes two requests to the same route and looks for a marker on the rendered section. A marker in the HTML helps catch an implementation that only adds the intended layout after JavaScript runs.

import assert from "node:assert/strict";

async function agenda(cookie) {
  const response = await fetch("http://localhost:3100/agenda", {
    headers: cookie ? { Cookie: cookie } : {},
  });
  assert.equal(response.status, 200);
  return response.text();
}

const [standard, preview] = await Promise.all([
  agenda(""), agenda("agenda-preview=1"),
]);
assert.match(standard, /<section data-agenda="standard"/);
assert.doesNotMatch(standard, /<section data-agenda="preview"/);
assert.match(preview, /<section data-agenda="preview"/);
assert.doesNotMatch(preview, /<section data-agenda="standard"/);
console.log("Both agenda layouts arrived in the server HTML.");

Now open http://localhost:3100/agenda in a fresh browser profile. You should see the session title without a room button. In that local page's browser console, set the demo cookie and reload.

document.cookie = "agenda-preview=1; Path=/; SameSite=Lax";
location.reload();

Click Show room and look for Room 204. Click Hide room and the room should disappear. This second check proves the component became interactive. If the server response test passes but the click fails, inspect the browser console for a hydration error before changing the flag rules.

Remove the fixture and reload once more. The button should disappear and the agenda title should remain.

document.cookie = "agenda-preview=; Path=/; Max-Age=0";
location.reload();

The reload is deliberate. Editing the cookie in an already open document doesn't rerun its Server Component. In your app, use the normal session-change flow to request a fresh server render when a visitor signs in, signs out, or leaves a preview group.

Choose where the next flag should be evaluated

For a decision needed in the initial HTML, give the agent an observable requirement. Ask it to show the two HTTP responses, then click the interactive control in the preview. The first check catches an incorrect layout. The second catches correct HTML that never becomes interactive.

If a later feature depends on an action entirely within the browser, evaluate whether its flag belongs in the client tree. The one-shot local flags guide covers both placements. This agenda only needs one server decision. Updating its checked-in rule takes a deployment. Keep that tradeoff in view if the event organizer needs to pause a preview while attendees are already arriving.

Manage the agenda rollout in Cloud

Create a GrowthBook workspace when the organizer needs to adjust a preview audience while your Next.js app is serving attendees.

Get Started with GrowthBook

Ready to ship faster?

No credit card required. Start with feature flags, experimentation, and product analytics—free.

Simplified white illustration of a right angle ruler or carpenter's square tool.White checkmark symbol with a scattered pixelated effect around its edges on a transparent background.