Experiments

Green release: what it is and how it works

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

Shipping code to production and releasing it to users are two different things — and the gap between them is exactly where a green release lives.

Shipping code to production and releasing it to users are two different things — and the gap between them is exactly where a green release lives. The pattern comes from blue-green deployments, where two identical environments run in parallel and traffic shifts from one to the other only after the new version has been validated. That validation step is what earns the "green" signal: not just deployed, but confirmed safe to proceed.

This article is for engineers, PMs, and data teams who want a clear, practical understanding of how green releases work — not just the concept, but the mechanics behind it. Here's what you'll learn:

  • How the blue-green model works and what the alternating environment cycle actually means
  • How traffic ramps up in stages and how guardrail metrics gate each step
  • How automated rollback protection works, and when to automate versus keep a human in the loop
  • How green releases differ from A/B experiments in both purpose and decision logic
  • How approval workflows and audit trails make the pattern governable at scale

The article moves in that order — from the foundational model to the operational mechanics to the governance layer. If you're new to the concept, start from the top. If you're already running blue-green deployments and want to understand the monitoring and approval layers, the later sections stand on their own.

Green release means a role in a deployment cycle, not a quality label

The term "green release" is most precisely understood within the context of blue-green deployments — a release strategy designed to update production applications with zero downtime. To define it accurately, you need to understand the two-environment architecture it comes from, because "green" doesn't describe a fixed environment or a universal quality label. It describes a role in a deployment cycle.

The blue-green model: where the term comes from

A blue-green deployment runs two identical instances of a production application behind a load balancer. At any given moment, one environment is live and serving user traffic; the other is idle and available for updates. The convention is to call the live environment "blue" and the updated environment "green" — though as we'll cover shortly, those roles aren't permanent.

The green environment is where your team deploys new code. It receives updates from your CI pipeline, gets tested, and is validated for stability before any real users touch it. Once the green environment is confirmed stable and new features are verified as working, traffic is shifted from blue to green. That moment of promotion — when the green environment takes over production traffic — is what practitioners mean by a green release.

The blue environment doesn't disappear after cutover. It stays on standby as an immediate rollback target. If something goes wrong after the green release, traffic can be redirected back to blue without redeploying the previous version from scratch. That rollback capability is one of the primary reasons teams adopt this pattern in the first place.

What makes a release "green" — the validation threshold

Beyond the infrastructure definition, "green release" carries a quality signal: the release has been validated and cleared for full production traffic. A release isn't green simply because it's been deployed to the green environment — it's green because it has passed whatever monitoring and verification criteria the team has established.

In practice, this means watching guardrail metrics — error rates, latency, conversion rates — during a controlled exposure period before committing to full rollout. GrowthBook operationalizes this through Safe Rollouts — running the new release as a short-term A/B test against guardrail metrics, surfacing a "Ready to ship" status only when no regressions are detected and the monitoring window has completed. That status is the functional equivalent of a green signal: no regressions, safe to proceed.

This framing matters because it separates two things that often get conflated: deployment and release. Code can be deployed to the green environment — sitting in production infrastructure — without being released to users. The green release happens when the validation threshold is crossed and traffic is fully promoted. Feature flags enable exactly this separation, allowing teams to deploy code to production but activate it only once it's earned that green status. Feature flags support broad SDK coverage across server-side, client-side, mobile, and edge runtimes, and evaluate entirely in-process with zero network latency — so the separation between deployment and release adds no performance cost.

Blue and green are positional labels that swap with every deployment

One source of confusion worth addressing directly: "green" does not permanently mean "new code" and "blue" does not permanently mean "stable production." The roles alternate with every deployment cycle.

After the first cutover, green becomes the live production environment. In the next deployment cycle, blue receives the new updates, gets validated, and is promoted to production — while green becomes the standby rollback target. Then the cycle repeats in reverse again.

This means the terms blue and green are positional labels, not quality judgments. At any point in time, whichever environment is live is the stable one. The environment receiving updates is the one being validated. Keeping this alternating cycle in mind prevents a common misconception: that green always means "risky" or "untested" and blue always means "safe." After the first deployment, that framing is simply wrong.

The practical implication is that teams running blue-green deployments need clear documentation or tooling to track which environment is currently live — because the answer changes with every release.

Gradual rollout mechanics: traffic ramps, guardrails, and what happens when something breaks

A green release is not a binary switch. The entire point of the pattern is that traffic moves incrementally from zero to full exposure, with monitoring running continuously throughout that progression. Understanding the mechanics — the specific stages, the statistical guardrails, and what happens when something goes wrong — is what separates a green release from a deployment that just happens to be slow.

Think of it as a dimmer switch for your features rather than an on/off button. The ramp gives you production evidence before you're fully committed.

The traffic ramp-up schedule

In practice, a green release progresses through defined traffic stages rather than a freeform crawl. GrowthBook's Safe Rollouts follow a fixed schedule: 10% → 25% → 50% → 75% → 100%. That entire ramp completes within the first 25% of whatever monitoring duration you configure.

If you set a four-day monitoring window, your feature goes from 10% to full traffic during day one. The remaining three days monitor the fully rolled-out feature against your guardrail metrics. This structure matters because it removes human delay from the expansion decision — the ramp advances on schedule, while the monitoring system handles the question of whether it should have.

Starting at 10% rather than 50% reflects a straightforward principle: risk should be proportional to confidence. When a change first reaches production, the team has the least confidence in it. A small initial blast radius means a regression visible in that early cohort can be caught before it reaches the majority of users.

Research from Firetiger suggests roughly two-thirds of rollout-related incidents would have been caught at a smaller ramp percentage) if per-cohort signals had been watched — the regression was visible early, but global metrics looked fine so the ramp expanded anyway.

How guardrail metrics gate the rollout

The ramp schedule handles traffic distribution. Guardrail metrics handle the question of whether the rollout is actually safe to continue.

Guardrail metrics are the health and business signals you care most about protecting: error rates, latency, conversion rates. You select them before the rollout begins, and the monitoring system watches them continuously throughout the ramp — not just at the end of the configured window.

The statistical mechanism matters here. Standard A/B test analysis is designed to be run once, at the end of a fixed period — running it repeatedly while the test is live inflates the chance of a false alarm. GrowthBook uses one-sided sequential testing instead, which is designed for continuous monitoring: it can flag a regression at any point during the rollout without increasing the rate of false positives. The practical result is a concept called the Metric Boundary: the threshold at which the system concludes the rollout is causing harm. That threshold is always set to zero — any statistically confirmed harm to a guardrail metric, no matter how small, marks the rollout as failing. For a payment flow or a latency-sensitive API, even a small regression is unacceptable, so the conservative threshold is intentional.

One practical note on metric selection: choosing too many guardrail metrics increases the chance of false positives. A focused set of critical metrics is more useful than comprehensive coverage.

Rollout status and automatic rollback

During the monitoring window, the rollout surfaces one of five status states: a countdown indicating monitoring is in progress, "Unhealthy" when traffic assignment looks imbalanced, "Guardrails Failing" when a regression has been detected, "Ready to Ship" when the duration completes without regressions, and "No Data" when no traffic has been recorded after 24 hours.

Each status maps to a concrete action. "Guardrails Failing" means you should consider reverting. "Unhealthy" points to a likely implementation problem — GrowthBook also runs automatic checks for sample ratio mismatch and multiple exposures to catch these issues. "Ready to Ship" is the green light.

The Auto Rollback toggle determines how the system responds to a guardrail failure. When enabled, GrowthBook automatically disables the rollout rule if a guardrail metric fails significantly — no human intervention required. When disabled, the team retains manual control. For teams shipping payment flows, ML models, or any change where a regression is genuinely unacceptable, the automatic path removes the latency between detection and response.

Safe rollouts vs. standard experiments

It's worth distinguishing the green release pattern from a standard A/B experiment, even though both use the same statistical engine under the hood. A Safe Rollout runs as a short-term A/B test — control receives the existing value, rollout receives the new value — but the decision logic is different.

A standard experiment is optimized for learning: you're measuring long-term impact and waiting for conclusive results. A Safe Rollout is optimized for operational safety: you're watching for harm, and if the monitoring period ends without evidence of regression, the guidance is to ship. Inconclusive results are not a reason to hold. The absence of detected harm is sufficient signal to proceed.

Rollback is only as fast as your previous environment is ready

The promise of a green release isn't just faster deployments — it's the ability to undo them just as fast. When something breaks in production, the difference between a two-minute recovery and a two-hour scramble often comes down to whether your previous environment is still standing by, ready to receive traffic, or whether it's been torn down and replaced. Green releases are designed around the former.

Why green releases make rollback structurally simple

In a blue-green deployment, the inactive environment isn't discarded after the cutover — it stays intact. That architectural choice is what makes rollback trivially mechanical: you switch traffic back to the previous environment rather than redeploying code, rebuilding containers, or untangling a rolling deployment, where rollback means pushing another deployment through the same pipeline you just used — under pressure, while users are experiencing the problem. With blue-green, the "rollback" is the same operation as the original release: a traffic switch. As Gearset describes it, "all you need to do is switch which colour is currently active, without replacing the inactive colour as you would with part of a release."

One practical decision remains: whether to cut all traffic at once or gradually. Switching all users simultaneously simplifies state management — you always know exactly which environment every user is on. A gradual switchover, however, limits blast radius if something goes wrong mid-rollout, since you can abort before the full user base is affected. Neither approach is universally correct; the right choice depends on how much complexity your team wants to manage versus how much exposure you're willing to accept during the transition window.

Automated guardrail monitoring: catching regressions before you notice them

The structural rollback advantage is reactive — you have to detect a problem before you can act on it. The more sophisticated layer is proactive: automated metric monitoring that can trigger a rollback before your on-call engineer has even opened their laptop.

Statistical guardrails implement this pattern by watching guardrail metrics continuously throughout the ramp — not just at the end — and flagging failures the moment statistical certainty is reached. When Auto Rollback is enabled, the system responds immediately. When it's disabled, the status is still surfaced for a human to act on.

Auto rollback removes latency; human judgment preserves context — both have a place

There's a legitimate debate in the DevOps community about whether automatic rollbacks are actually desirable. Octopus Deploy argues they should be treated as a last resort, and their reasoning is worth taking seriously: many deployment failures will also prevent a successful rollback (an expired credential that broke the deployment will break the rollback too), database state changes may require human judgment about what to preserve, and automatically reverting removes the opportunity to observe and learn from the failure condition.

These concerns are real — but they apply specifically to infrastructure-level deployment rollbacks, where you're redeploying code, managing database migrations, and dealing with stateful systems. Feature-flag-based rollbacks sidestep most of them. Disabling a flag rule doesn't touch your database, doesn't require a redeployment, and doesn't risk compounding the original failure with a broken recovery process.

This distinction explains why GrowthBook's Auto Rollback is a configurable toggle rather than a forced default. The goal is automation that can act on your behalf when you need speed, but that can also be configured to surface the problem and wait for a human decision when context matters more than latency. Teams with zero tolerance for certain regressions (a refactored payment flow where any error rate increase is unacceptable) can automate fully. Teams that want observability with human judgment in the loop can leave auto-rollback off and act on the status signals manually. The structural safety net — the idle environment ready to receive traffic — exists either way.

Green release vs. experiments

Green releases and A/B tests are often discussed in the same breath, and they do share some infrastructure — but conflating them is a mistake that leads to misusing both. They answer different questions, operate under different decision logic, and exist for fundamentally different purposes. Understanding where one ends and the other begins makes you better at deploying software and better at learning from it.

Green releases ask "is this safe?"; experiments ask "which version wins?"

A green release monitors guardrail metrics — error rates, latency, conversion rates — to detect whether a new change is causing harm. The goal is operational: confirm that nothing is broken, then proceed. As GrowthBook's documentation puts it, the primary goal of a safe rollout is "to ensure a safe release, not to measure long-term impact."

An A/B experiment, by contrast, is a hypothesis-driven learning mechanism. It tracks goal metrics alongside guardrails, requires sufficient traffic to reach statistical power, and is designed to produce a defensible answer about which variation produces better outcomes. You run an experiment when you're genuinely uncertain about the impact of a change and need data to make a product decision — not just to confirm that nothing caught fire.

Inconclusive results mean ship in a green release, keep running in an experiment

This is where the two tools diverge most sharply in practice.

In a green release, the default outcome is to ship. If you monitor a rollout for a defined window and see no meaningful regression in your guardrail metrics, you proceed — even if results are inconclusive. The logic is explicitly biased toward action. GrowthBook's documentation states this directly: "If results are still inconclusive after the configured duration, ship — there's no clear evidence that the feature is harmful." Inconclusive is acceptable because the bar was never "prove this is better." The bar was "confirm this isn't worse."

In an A/B experiment, inconclusive results mean you keep running. Experiments require statistical thresholds — a p-value below a defined cutoff for frequentist approaches, or a chance-to-win above a high threshold for Bayesian ones — before a decision is warranted. Stopping early without meeting those thresholds undermines the validity of the result. The experiment is a sensitive statistical instrument, and it demands patience that a green release explicitly does not.

Shared infrastructure, different purpose

One reason practitioners conflate these tools is that they can run on the same underlying platform. Feature flags, traffic splitting, and metric monitoring are common to both. GrowthBook uses the same analysis engine for both Safe Rollouts and Experiments — but treats them as distinct workflows with different configurations and different decision criteria.

The shared infrastructure is a feature, not a sign that the tools are equivalent. It means you can graduate from a green release into a full experiment on the same platform without rebuilding your instrumentation. But the tooling similarity doesn't change what each is designed to do.

Confidence about correctness calls for a green release; uncertainty about impact calls for an experiment

Use a green release when you're confident a feature is correct — the design is finalized, the code is reviewed, the intent is clear — but you want to reduce the blast radius of deployment risk. You're not trying to learn anything new; you're trying to ship safely.

Use an A/B experiment when you're genuinely uncertain about impact. Maybe you've built a new onboarding flow and want to know whether it improves activation. Maybe you've redesigned a checkout page and need to know whether conversion goes up or down. That uncertainty is what an experiment is built to resolve. As GrowthBook's documentation advises: "If you're more uncertain about a feature and want to learn about its impact, run a regular Experiment instead."

The two tools can and should coexist in a mature engineering workflow. A team might use a green release to safely deploy a backend infrastructure change, then run an A/B experiment to evaluate a product hypothesis in the same sprint. They're not competing approaches — they're complementary ones, as long as you're clear about which question you're actually trying to answer.

Governance is what makes a green release auditable, not just elegant

The mechanical side of a green release — spinning up a parallel environment, routing traffic incrementally, monitoring for regressions — gets most of the attention. But the governance layer deserves equal scrutiny. A green release strategy can still fail if an unreviewed change reaches production, if two engineers edit the same flag simultaneously without a conflict resolution path, or if there's no audit record of who approved what and when. Structured approval flows, draft management, and change controls are what make a green release governable at scale, not just technically elegant.

Drafts as a safety buffer before go-live

When a feature flag change is authored, it shouldn't immediately affect what users see. A well-designed system creates an unpublished draft revision automatically — a staging layer that accumulates changes invisibly until someone explicitly promotes them to live. This draft state is the governance equivalent of the green environment itself: a place where changes exist and can be inspected before they have any real-world effect.

In GrowthBook, every modification to a feature flag creates a new draft revision that is invisible to end users and to SDKs until published. Changes can be batched — an engineer can make multiple edits across a flag's configuration and publish them together with an optional commit message, reducing the number of discrete publish events that need review. Once a revision is published, it becomes immutable. Reverting to a prior state requires explicitly selecting a previous version from the revision history and triggering a revert — there's no silent overwriting of what went live.

Handling merge conflicts in concurrent releases

Teams running multiple green releases in parallel will eventually hit the scenario where two people edit the same flag at the same time. One publishes while the other still has an open draft, and now the draft has diverged from the live version. Without a structured conflict resolution path, the second publish either silently overwrites the first or fails in an opaque way.

GrowthBook handles this with auto-merge for non-overlapping changes — if two engineers edited the same flag in different environments, the system resolves the conflict automatically. When changes do overlap, the system surfaces a diff-based interface similar to Git's conflict resolution view, requiring manual resolution before the draft can be published. This is a meaningful safeguard for teams where feature flags are shared infrastructure touched by multiple squads.

Requiring approvals before publishing

For teams that need a formal review gate, approval flows add a four-eyes requirement to the publish step. In GrowthBook, approval flows are available for Enterprise customers and can be configured per-environment or applied globally. When enabled, an author must request a review — with a detailed comment — before a draft can be published. The pending request appears in the Drafts tab on the Features overview page with a "Pending Review" status.

Reviewer eligibility is scoped to anyone with Edit or Add permissions for feature flags, with one explicit exclusion: the person who created the request cannot approve their own change. Reviewers have three options — leave a comment without taking formal action, request changes (which blocks publishing), or approve (which enables publishing). A "Reset review on changes" toggle prevents a common circumvention pattern where someone gets approval and then modifies the draft before publishing; with this enabled, any post-approval edit invalidates the existing approval and requires a fresh review. Admins retain a bypass option for urgent situations, which is surfaced explicitly in the UI rather than hidden — an honest acknowledgment that governance sometimes needs an escape valve.

Audit trails and permission controls

Control before go-live is only half the governance story. Accountability after the fact requires a complete record of what changed, who approved it, and when it went live. Feature audit logs and versioning provide this history for feature flag changes, and exportable audit logs allow that data to flow into external compliance systems. The Compare Revisions tool provides a visual diff between any two versions, which is useful both for post-incident review and for pre-publish verification.

Permission architecture reinforces these controls at the role level. A dedicated FeaturesBypassApprovals policy exists specifically to grant bypass capability without granting broader administrative access — a principle of least privilege applied to the approval workflow itself. For organizations operating under SOC 2 or ISO 27001 frameworks, this combination of immutable revision history, structured approval gates, and exportable logs provides the evidentiary foundation that compliance audits require.

The discipline that makes the pattern work: define harm before you start the ramp

A green release is not a single tool — it's a set of interlocking decisions: how you separate deployment from release, how you define harm before you ship, how you handle the moment something goes wrong, and how you keep the whole process auditable. The pattern works because each layer reinforces the others. The traffic ramp limits blast radius. The guardrail metrics catch what the ramp exposes. The idle environment makes recovery fast. The approval workflow keeps humans accountable for what goes live.

The tension worth holding onto: automation and human judgment are not opposites here. Auto rollback is valuable precisely because it removes latency in the worst moments — but it's a toggle, not a mandate. The right setting depends on what you're shipping and what a regression actually costs you. A payment flow and a UI copy change do not deserve the same answer.

If you've read this far, you already understand the pattern well enough to use it. The mechanics are learnable; the harder part is building the habit of defining your guardrail metrics before you start the ramp, not after something breaks. That discipline — deciding what "harm" means while you're calm, not while you're on-call — is what makes the rest of the system work. This article was written to give you a clear enough picture of the whole that you can make that call confidently.

Where to start depends on which layer you're missing

If you're new to blue-green deployments: Start with infrastructure. Get two environments running behind a load balancer and practice the traffic switch with a low-stakes change before adding monitoring or governance.

If you have blue-green but rollbacks are still manual and stressful: Add instrumentation. Pick two or three guardrail metrics that matter most to your system and wire them into a monitoring layer before your next significant release.

If you have the ramp and metrics but no governance layer: Check whether your feature flag tooling supports draft revisions and approval flows. GrowthBook's Safe Rollouts handle all three layers in a single workflow.

If you're deciding between a green release and an A/B experiment: Return to the core question — are you trying to confirm this is safe, or are you genuinely uncertain whether it's good? The answer tells you which tool to reach for.

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.