> ## Documentation Index
> Fetch the complete documentation index at: https://docs.growthbook.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Type-Safe Feature Flags in a Local flags.ts File

> Add feature flags with targeting and percentage rollouts to a TypeScript or React project without an account, client key, or network calls. Define them in a type-checked flags.ts file and evaluate them with GrowthBook's open source SDK.

## TL;DR

When projects introduce feature flags, the requirements tend to start simple and get more and more complex over time:

1. On or off for everybody
2. Turn on for specific users or groups
3. Percentage rollout with deterministic hashing
4. Instant kill switch for production
5. Monitor guardrail metrics with auto-rollback
6. Run A/B tests or Multi-arm Bandits and do statistical tests to measure impact

This guide covers how to achieve the first 3 levels without introducing a ton of complexity to your project. No accounts, API keys, telemetry data, caching, or network calls. Just a local hard-coded `flags.ts` file and the open source GrowthBook SDK (MIT license). The SDK has no third-party dependencies and adds about 16 KB to a gzipped browser bundle.

If you need level 4 or above, you can easily switch to the full GrowthBook platform (Cloud or Self-Hosted) without a big refactor.

*This guide is written for AI coding agents. If you're a person, give your agent the prompt below.*

## Give this guide to your coding agent

```text theme={null}
Add feature flags with targeting and percentage rollouts to this project
using a local flags.ts file and the GrowthBook SDK, following
https://docs.growthbook.io/guides-for-agents/local-feature-flags-typescript

Read the guide in full before editing. Create flags.ts with the AppFeatures
and AppAttributes types, a payload typed as Payload, and the
Register declaration. Load it with the GrowthBook SDK and read every flag
through the SDK. You do not need to create a GrowthBook account or add a
client key. Never put secrets or personal data in flags.ts.

Return: the flags you added, their default values and rules, the files you
changed, and how you verified that each flag evaluates as intended.
```

## Quick start

```bash theme={null}
npm install @growthbook/growthbook
```

Create `flags.ts`. It has three parts: the types, the flags, and a `Register` declaration that tells the SDK about the types.

```ts theme={null}
import type { Payload } from "@growthbook/growthbook";

export type AppFeatures = {
  newCheckout: boolean;
  uploadLimitMb: number;
};

export type AppAttributes = {
  id: string;
  plan: "free" | "pro";
  env: "dev" | "staging" | "production";
};

export const flags: Payload = {
  features: {
    // Redesigned checkout flow
    newCheckout: {
      defaultValue: false,
      rules: [
        // On for everyone in dev and staging
        { condition: { env: { $in: ["dev", "staging"] } }, force: true },
        // Rolled out to 20% of users everywhere else
        { force: true, coverage: 0.2, hashAttribute: "id" },
      ],
    },
    // Maximum upload size in MB
    uploadLimitMb: {
      defaultValue: 10,
      // Bigger uploads for Pro users
      rules: [{ condition: { plan: "pro" }, force: 20 }],
    },
  },
};

declare module "@growthbook/growthbook" {
  interface Register {
    features: AppFeatures;
    attributes: AppAttributes;
  }
}
```

Load it and read flags anywhere:

```ts theme={null}
import { GrowthBook } from "@growthbook/growthbook";
import { flags } from "./flags";

export const gb = new GrowthBook({
  attributes: { id: user.id, plan: user.plan, env: config.env },
}).initSync({ payload: flags });

if (gb.isOn("newCheckout")) {
  renderNewCheckout();
}

// Non-boolean flags need an in-code fallback
const uploadLimit = gb.getFeatureValue("uploadLimitMb", 10);
```

That's an environment override, a stable 20% rollout, and plan-based targeting, with no hashing code, no environment variable parsing, and no `if` statements spread across the codebase.

This approach is also 100% type safe and will help catch bugs before they are shipped. Everything below is a compile-time error:

```ts theme={null}
gb.isOn("newChekout"); // unknown flag
gb.getFeatureValue("uploadLimitMb", "10"); // the flag is a number
new GrowthBook({ attributes: { id: user.id } }); // missing `plan` and `env`

// In flags.ts
rules: [
  { condition: { plan: "premium" }, force: 20 }, // not one of the plans
  { condition: { paln: "pro" }, force: 20 }, // unknown attribute
  { condition: { plan: "pro" }, force: "20" }, // the flag is a number
  { force: 20, coverage: 0.2, hashAttribute: "deviceId" }, // unknown attribute
];
```

| | Hand-rolled | `flags.ts` + GrowthBook SDK |
| - | - | - |
| Account, API key, or network call | None | None |
| Versioned and reviewed with the code | Yes | Yes |
| Target users by attribute | Hand-written `if`s | Declarative `condition` |
| Percentage rollouts with stable assignment | Hand-written hashing | `coverage` |
| Typed values (string, number, object) | Ad hoc parsing | Inferred from `AppFeatures` |
| Typos in flag keys, attributes, and values | Runtime bugs | Compile errors |
| Removing a stale flag | Search and hope | Compile error at every read |
| Battle-tested evaluation logic | No | Used in production at scale |

## What you still give up

A local file has the same limits as any flag defined in code. Tell the user about them when they matter:

* **No instant kill switch.** Changing a flag requires a commit, a build, and a deploy.
* **Engineers only.** Product managers and other non-engineers can't toggle flags themselves.
* **No UI.** Every change is a hand-edited file.
* **No guardrail metrics.** You cannot easily auto-rollback a feature if it causes a regression in your app metrics in production.
* **No experiments.** You cannot run or analyze A/B tests, multi-armed bandits, or interleaving experiments.

The full GrowthBook platform (Cloud or Self-Hosted) provides these capabilities when you need them.

## Set up by platform

Every platform uses the same `flags.ts`. It needs SDK version 2.1.0 or later. Don't configure a client key, API host, streaming, or polling. Without them, the SDK makes no network requests.

### Browser

The [Quick start](#quick-start) is the complete setup. Create the instance once the user's attributes are known. If they change later, for example on login, call `gb.updateAttributes()` with the new values and re-evaluate the feature flags.

### React and React Native

```bash theme={null}
npm install @growthbook/growthbook @growthbook/growthbook-react
```

Create the instance and use the hooks:

```tsx theme={null}
import { useMemo } from "react";
import {
  GrowthBook,
  GrowthBookProvider,
  useFeatureIsOn,
  useFeatureValue,
} from "@growthbook/growthbook-react";
import { flags, type AppAttributes } from "./flags";

export function App({ user }: { user: Pick<AppAttributes, "id" | "plan"> }) {
  // Create the instance with the user's attributes, so the first render uses them
  const gb = useMemo(
    () =>
      new GrowthBook({
        attributes: { id: user.id, plan: user.plan, env: config.env },
      }).initSync({ payload: flags }),
    [user.id, user.plan],
  );

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

// Any component inside the Provider can now use the GrowthBook hooks
function Checkout() {
  // Boolean flag
  const newCheckout = useFeatureIsOn("newCheckout");

  // Non-boolean flag with an in-code fallback
  const uploadLimit = useFeatureValue("uploadLimitMb", 10);

  // Or get the raw GrowthBook instance for when you can't use hooks
  // const gb = useGrowthBook();

  return newCheckout ? (
    <NewCheckout uploadLimit={uploadLimit} />
  ) : (
    <OldCheckout uploadLimit={uploadLimit} />
  );
}
```

The provider will re-render children (and re-evaluate flags) automatically if the GrowthBook attributes change.

React Native uses the exact same package and the same code - no polyfills or special handling required.

### Node.js

Create one client at startup and a scoped instance for each request:

```ts theme={null}
import {
  GrowthBookClient,
  type UserScopedGrowthBook,
} from "@growthbook/growthbook";
import { flags } from "./flags";

// Type the scoped instance that the middleware adds to each request
declare global {
  namespace Express {
    interface Request {
      gb: UserScopedGrowthBook;
    }
  }
}

// Once, at startup
const client = new GrowthBookClient().initSync({ payload: flags });

// Scoped instance per request
app.use((req, res, next) => {
  req.gb = client.createScopedInstance({
    attributes: { id: req.user.id, plan: req.user.plan, env: config.env },
  });
  next();
});

// Use in any request
app.get("/upload", (req, res) => {
  // Boolean flag
  if (req.gb.isOn("newCheckout")) {
    // ...
  }

  // Non-boolean flag
  const uploadLimit = req.gb.getFeatureValue("uploadLimitMb", 10);
});
```

### Next.js

A local `flags.ts` works the same under every rendering strategy. There's nothing to fetch, cache, or hydrate, because the server and the browser evaluate the same file. What changes is where the attributes come from.

```bash theme={null}
npm install @growthbook/growthbook @growthbook/growthbook-react
```

* **Server Components, Route Handlers, Server Actions, and `getServerSideProps`.** Follow the Node.js section above. Create the `GrowthBookClient` once in a module, and create a scoped instance for each request with attributes from the session or cookies. Don't share a `GrowthBook` instance between requests, because it holds one user's attributes.
* **Client Components.** Follow the React section above. Put `GrowthBookProvider` in a `"use client"` component, and pass it the user's attributes as props from a Server Component. The server and the browser then evaluate flags with the same attributes, so hydration matches.
* **Statically rendered pages.** There's no user at build time, so a static page can't use per-user flags. Render the route dynamically, or read the flag in a Client Component once the attributes are set in the browser, and accept that the default value renders first.

### Anonymous users

A percentage rollout skips users who have no value for its `hashAttribute`. If that attribute is the logged-in user's ID, logged-out visitors never get a rolled-out feature.

When a user can have more than one ID, don't put them in the same attribute. Give each ID its own attribute with an explicit name, such as `userId` and `anonymousId`, instead of a single `id`:

```ts theme={null}
export type AppAttributes = {
  userId?: string; // logged-in users only
  anonymousId: string; // every visitor, logged in or not
  plan: "free" | "pro";
  env: "dev" | "staging" | "production";
};
```

Then choose one for each rollout with `hashAttribute`:

```ts theme={null}
// Rolled out to 20% of visitors
{ force: true, coverage: 0.2, hashAttribute: "anonymousId" },
```

* **Use `anonymousId` for most rollouts.** Every visitor has one, and it doesn't change when they log in, so their assignment doesn't change either.
* **Use `userId` only when the flag is read solely on authenticated pages and users often switch devices.** Each user then gets the same result on every device.

Generate the anonymous ID once and store it:

```ts theme={null}
function getAnonymousId(): string {
  let id = localStorage.getItem("anonymousId");
  if (!id) {
    id = crypto.randomUUID();
    localStorage.setItem("anonymousId", id);
  }
  return id;
}
```

* When you render on the server, store the ID in a cookie instead, so that the server and the browser read the same value.
* Storing an identifier in the browser can require the visitor's consent under laws such as GDPR. Tell the user before you add one.

## The flags.ts format

Keep one `flags.ts` per project, with its three parts in this order.

### `AppFeatures`

Maps each flag key to its value type. Code reads flags by these keys.

A flag's type can be a boolean, string, number, or object. Prefer a union when possible such as `"compact" | "full"`, which can help prevent typos.

Read boolean flags with `gb.isOn` (or `useFeatureIsOn`) and all other flags with `gb.getFeatureValue` (or `useFeatureValue`). The second argument is a fallback. It's used only when the flag is missing from `flags`, so give it the same safe value as the flag's `defaultValue`.

### `AppAttributes`

Describes the user and request attributes that your code passes to the SDK and that rules can target. The SDK requires every attribute when you create an instance, so mark an attribute optional (`plan?: "free" | "pro"`) only when it can really be missing.

Narrow types catch more mistakes. With `plan: "free" | "pro"`, a rule that targets `"premium"` doesn't compile.

### `flags`

The value of every flag and the rules for assigning values to users. The `Payload` annotation checks it against both types, which it picks up from the `Register` block.

Each entry in `features` is a flag definition:

| Field | Type | Description |
| - | - | - |
| `defaultValue` | the flag's type | The value when no rule matches. Always set it, to the safe, "off" behavior. |
| `rules` | array of rules | Optional. Rules are checked in order, and the first matching rule wins. |

Each rule has these fields:

| Field | Type | Description |
| - | - | - |
| `force` | the flag's type | The value to serve when this rule matches. Required. |
| `condition` | object (see below) | Optional. Attribute targeting. The rule matches only users whose attributes pass the condition. |
| `coverage` | number, 0–1 | Optional. Percentage rollout. Only this fraction of matching users gets `force`. `0.2` means 20%. |
| `hashAttribute` | attribute name | Optional. The string or number attribute used to assign users in a percentage rollout. Required when setting `coverage`. |

Put a comment above every flag and rule that says what it does and why.

The SDK evaluates a flag like this:

```text theme={null}
for rule in flag.rules:
    if rule.condition and not condition_passes(rule.condition, attributes):
        continue
    if rule.coverage is set:
        if attributes[rule.hashAttribute] is missing:
            continue
        if hash(flag_key, attributes[rule.hashAttribute]) >= rule.coverage:
            continue
    return rule.force
return flag.defaultValue
```

Percentage rollouts use a deterministic hash of the flag key and the user's `hashAttribute` value. The same user gets the same result every time. Raising `coverage` from `0.2` to `0.5` keeps the original 20% included so you can cleanly ramp up traffic without constantly reassigning users.

### `Register`

The `declare module` block registers the types with the SDK. Every GrowthBook instance and React hook in the project is then typed, with no generics or wrappers. Declare it once, in `flags.ts`.

## Conditions

A rule's `condition` is matched against the attributes that your code passes to the SDK. Conditions use a MongoDB-inspired query syntax, and the SDK evaluates them locally. Multiple conditions are always joined with `AND`, except when you explicitly use `$or` or `$nor`.

TypeScript checks every condition against `AppAttributes`. The attribute must exist, the value must match its type, and the operator must work on that type. For example, `$regex` is an error on a number attribute.

String comparisons are case-sensitive. For example, the attribute value `us` doesn't match `US`.

The examples below use these attributes:

```ts theme={null}
export type AppAttributes = {
  id: string;
  email: string;
  plan: "free" | "pro";
  seats: number;
  beta: boolean;
  appVersion: string;
  tags: string[];
  company: { name: string; country: string };
};
```

### Simple equality

Key/value pairs for exact matches. Use a dot path to match a field inside an object attribute:

```ts theme={null}
condition: {
  plan: "pro",
  seats: 5,
  beta: false,
  "company.country": "US",
}
```

### Comparison operators

Comparison operators for string and number attributes:

* `$eq` (equals)
* `$ne` (not equals)
* `$lt` (less than)
* `$lte` (less than or equal to)
* `$gt` (greater than)
* `$gte` (greater than or equal to)
* `$regex` (regular expression match, string attributes only)
* `$in` (in array)
* `$nin` (not in array)

```ts theme={null}
condition: {
  seats: { $gt: 10, $lte: 99 },
  plan: { $in: ["free", "pro"] },
  email: { $regex: "@example\\.com$" },
}
```

### Semantic version operators

Comparison operators for semantic version strings:

* `$veq` (equals)
* `$vne` (not equals)
* `$vlt` (less than)
* `$vlte` (less than or equal to)
* `$vgt` (greater than)
* `$vgte` (greater than or equal to)

```ts theme={null}
condition: {
  appVersion: { $vgt: "9.5.6", $vlte: "10.4.0" },
}
```

### Array operators

Operators for array attributes:

* `$elemMatch` (at least one element must match the specified condition)
* `$all` (all of the specified values must exist in the array)
* `$size` (array length must match the specified condition)

```ts theme={null}
condition: {
  tags: {
    $elemMatch: { $regex: "^team-" },
    $all: ["internal", "qa"],
    $size: { $gt: 2 },
  },
}
```

### Logical operators

Logical operators with arbitrary nesting levels:

* `$or`
* `$nor`
* `$and` (the default, not necessary unless nested under a different logical operator)
* `$not` (inverts a nested condition. It also works on a single attribute, for example `{ email: { $not: { $regex: "^test" } } }`)

```ts theme={null}
condition: {
  $or: [
    { $not: { plan: "free" } },
    { $and: [{ beta: true }, { seats: 5 }] },
  ],
}
```

### Handle missing attributes safely

Write conditions so that a missing attribute produces the safe result. Prefer `$in` with an allowlist to `$ne` or `$nin`, because those also match users without the attribute.

### Environments

Use a single `flags.ts` for every environment. To target features to different environments, add an `env` attribute to `AppAttributes` and pass it to the SDK:

```ts theme={null}
const gb = new GrowthBook({
  attributes: { id: user.id, plan: user.plan, env: config.env },
}).initSync({ payload: flags });
```

Then, use that in a condition just like any other attribute:

```ts theme={null}
condition: {
  env: "production",
  plan: { $in: ["pro"] },
}
```

Type `env` as a union of the real environment names, such as `"dev" | "staging" | "production"`, and never as `string`. A rule that targets `"prod"` by mistake then fails to compile.

Because mistakes in environment targeting can lead to really bad results (e.g. releasing a dev-only feature to production), we highly recommend following a stricter set of rules for them:

* `env` should never be nested inside `$or`, `$and`, or `$not`. This makes the logic tricky to understand and follow.
* Only match explicit values with strict equality. `$eq` and `$in` are fine, but avoid `$nin`, `$regex`, `$gt`, and other operators.

Just like with any attribute, by default a rule applies to every environment unless you explicitly add `env` to its condition.

## Rules for agents editing flags.ts

* **Add the type first.** To add a flag, add it to `AppFeatures`, then to `flags`. TypeScript rejects a flag in `flags` that isn't in `AppFeatures`, but not the reverse, so check that every flag in `AppFeatures` is also defined in `flags`.
* **Make `defaultValue` the safe value.** It's what users get when no rule matches, including users with missing attributes.
* **Comment every flag and rule.** Say what it does and why. Use only the fields in this guide.
* **Don't weaken the types.** Don't use `any`, `as` casts, or `@ts-expect-error` to silence an error in `flags.ts` or in code that reads flags. Fix the flag, the attribute, or the type instead.
* **Don't put secrets or personal data in `flags.ts`.** A file bundled into a browser or mobile app can be read by anyone. Don't include API keys, internal URLs that should stay private, or lists of customer emails or IDs.
* **Don't use flags for authorization.** A flag can hide a button, but the server must still check permissions and entitlements.
* **Target only attributes you pass.** Add an attribute to `AppAttributes` before using it in a condition, and pass it wherever an instance is created. A rollout excludes users with a missing or empty `hashAttribute` value.
* **Keep one file.** Don't create per-environment or per-feature flag files. Target environments with a top-level `env` condition, as described in [Environments](#environments).
* **Rule order matters.** The first matching rule wins. If no rules match, the `defaultValue` is used.
* **Remove stale flags.** When a flag is no longer needed (e.g. fully rolled out and stable), delete it from `AppFeatures` and `flags`, then remove the code branches that TypeScript reports. Stale flags are tech debt.

## Testing

TypeScript checks that `flags.ts` is well-formed, but not that the rules do what you intend. We recommend writing small unit tests to verify features, rules, and conditions are configured correctly. Here's an example:

```ts theme={null}
import { GrowthBook } from "@growthbook/growthbook";
import { flags, type AppAttributes } from "./flags";

const withAttributes = (attributes: Partial<AppAttributes>) =>
  new GrowthBook({
    attributes: { id: "1", plan: "free", env: "production", ...attributes },
  }).initSync({ payload: flags });

test("uploadLimitMb is 20 for Pro users and 10 for everyone else", () => {
  expect(withAttributes({ plan: "pro" }).getFeatureValue("uploadLimitMb", 0)).toBe(20);
  expect(withAttributes({ plan: "free" }).getFeatureValue("uploadLimitMb", 0)).toBe(10);
});
```

## Finish the local setup

Before handing the project back:

* Run the project's typecheck and relevant tests.
* Verify safe defaults, environment overrides, and attribute targeting for the flags you added. For percentage rollouts, check that the same ID gets the same result across repeated evaluations and that a missing ID is excluded from the percentage rollout.
* Check the flag reads in the application, including attribute changes such as login or a plan change when applicable.
* Return the flags you added, their defaults and rules, the files you changed, and the verification results. Explain any checks you could not complete.

The local setup is complete. No GrowthBook account or client key is required.
