PDFs up to {maxMb} MB.
}
// => PDFs up to 10 MB.
(no provider answered, so the default)
```
Calling `useFlag('max-upload-mb')` with no type arguments also works, but the value is typed as `boolean | string | number` and a typo is not caught.
## Read every flag at once
`useFlags()` from `@kitr/flags/react` returns every flag as one object, for a settings page or a debug panel:
```tsx
// app/components/settings/flags-panel.tsx
import { useFlags } from '@kitr/flags/react'
import type { flags } from '#app/flags'
export function FlagsPanel() {
const values = useFlags()
return {JSON.stringify(values, null, 2)}
}
// => { "new-dashboard": false, "max-upload-mb": 10, "invoice-layout": "classic" }
```
The object is frozen and stays the same object until the flags change, so it is safe to pass to memoised children.
## Read a flag outside React
Outside components, get the service from the container with `useFlags(app)` from `@kitr/flags`. Its reads are synchronous and answer from the current snapshot:
```ts
// app/lib/invoices/validate-upload.ts
import type { KitrApp } from 'kitr/app'
import { useFlags } from '@kitr/flags'
import type { flags } from '#app/flags'
export function checkUploadSize(app: KitrApp, file: File) {
const maxMb = useFlags(app).value('max-upload-mb')
if (file.size > maxMb * 1024 * 1024) return `Invoices must be under ${maxMb} MB.`
return null
}
```
| Method | Returns | Description |
| --- | --- | --- |
| `value(key)` | the flag's type | The current value: the snapshot, or the default before one exists. |
| `isEnabled(key)` | `boolean` | `true` only when the value is exactly `true`. |
| `snapshot()` | all values | One frozen object with every flag. |
| `resolve(context?)` | `Promise` of all values | Ask the providers for `context`. See below. |
| `hydrate(values)` | `void` | Load values the server resolved. |
| `subscribe(listener)` | unsubscribe function | Called after each resolve or hydrate that updates the snapshot. |
| `resolved` | `boolean` | Whether the snapshot came from a resolve or hydrate rather than defaults. |
| `definitions` | the definitions | What `app/flags.ts` declared. |
`isEnabled` is for boolean flags. On a number flag it is always `false`, even for a value of `1`; use `value()` there.
## Read flags on the server
On the server, one process answers many users at once, so flags are resolved per request. `resolveFlags(app, event, context)` from `@kitr/flags/server` asks the providers for this request's user and caches the answer on the request:
```ts
// server/controllers/dashboard-controller.ts
import type { HttpContext } from '@kitr/api'
import { resolveFlags } from '@kitr/flags/server'
import type { flags } from '#app/flags'
import { classicSummary, newSummary } from '#server/dashboard/summaries'
export default class DashboardController {
async show({ app, event }: HttpContext) {
const values = await resolveFlags(app, event)
return values['new-dashboard'] ? newSummary() : classicSummary()
}
}
```
The user comes from `locals.user.id` when [auth](/packages/auth) middleware has set it, so a percentage rollout gives Ada the same answer on every request. Pass more context as the third argument; it is merged over the user id and every provider receives it:
```ts
// server/controllers/invoices-controller.ts
import type { HttpContext } from '@kitr/api'
import { resolveFlags } from '@kitr/flags/server'
import type { flags } from '#app/flags'
export default class InvoicesController {
async uploadLimit({ app, event, locals }: HttpContext) {
const team = locals.team as { id: string; plan: 'free' | 'pro' }
const values = await resolveFlags(app, event, { teamId: team.id, plan: team.plan })
return { maxMb: values['max-upload-mb'] }
// => { maxMb: 10 }
}
}
```
The first call on a request runs the providers; later calls on the same request return the same object without asking again, even with different context. Resolve once, early, with the full context.
Inside a request, the request's own app (a fork of the server app) keeps the resolved values, so `useFlags(app).value('new-dashboard')` in a service called from that request answers for that user. The shared root app never keeps a resolved snapshot: `resolve()` on it returns the values but leaves `value()` at the defaults, so one user's answer can never leak to the next.
## Send the server's answer to the browser
The browser can't read `process.env`, and it may not know the user id when it boots. So the server resolves the flags and embeds the result in the page as a JSON script tag. When the client app boots, the flags provider reads that tag and loads it before the first render, without asking any provider.
`` from `@kitr/flags/react` renders the tag. In a server-rendered app, resolve in the root route's loader and put the tag in the document head:
```ts
// app/server/load_flags.ts
import { createServerFn } from '@kitr/actions'
import { resolveFlags } from '@kitr/flags/server'
import type { flags } from '#app/flags'
import { server } from '#server/main'
import { currentUserId } from '#server/session'
export const loadFlags = createServerFn({ method: 'GET' }).handler(async () => {
await server.boot()
return resolveFlags(server.app, { context: {} }, { userId: await currentUserId() })
})
```
```ts
// app/routes.ts
import { head, RootDocument } from './document'
import { loadFlags } from '#app/server/load_flags'
r.root({ head, loader: () => loadFlags(), component: RootDocument })
```
```tsx
// app/document.tsx
import { FlagsScript } from '@kitr/flags/react'
import { getRouteApi, HeadContent, Outlet, Scripts } from '@kitr/router'
const root = getRouteApi('__root__')
export function RootDocument() {
const flags = root.useLoaderData()
return (
)
}
```
The page now carries:
```html
```
Values are escaped (`<` becomes `<`), so a string flag can't close the tag. The client treats the embedded JSON as input: it keeps only declared keys, coerces each to its declared type, and falls back to the default for anything it can't read. A broken tag is ignored, and the provider resolves at boot instead.
Outside React, `flagsScript(values)` from `@kitr/flags/server` returns the same tag as a string, for a server that writes HTML by hand:
```ts
// server/pages/invoice_print.ts
import { flagsScript } from '@kitr/flags/server'
const head = `Invoice${flagsScript({ 'invoice-layout': 'compact' })}`
// => Invoice
```
During server rendering, `useFlag` answers from the app that renders the page. When that app has not resolved flags for this request, it renders defaults, and the browser's first render from the embedded snapshot can differ. For UI that must match on the first paint, read the value from the root loader's data on both sides.
In a single-page app with no server rendering, there is nothing to embed. The provider calls `resolve()` at boot in the browser with no context, so env variables and percentage rollouts don't apply until you resolve again with a user (next section).
## Resolve again after sign-in
In the browser, `resolve(context)` updates the snapshot, and every `useFlag` re-renders with the new answer. Call it once you know who the user is:
```tsx
// app/components/auth/after-sign-in.tsx
import { useApp } from '@kitr/react'
import { useEffect } from 'react'
export function ResolveFlagsFor({ userId }: { userId: string }) {
const app = useApp()
useEffect(() => {
void app.container.use('flags').resolve({ userId })
}, [app, userId])
return null
}
```
Render `` inside the signed-in layout. When Linus signs in, the percentage provider places him in or out of the 10%, and the dashboard switches without a reload. Call `resolve({})` on sign-out to drop back to the anonymous answer.
## Providers
A provider answers flags from one source. List them in `config/flags.ts` in priority order: the first one with an answer wins.
| Provider | Answers from | Silent when |
| --- | --- | --- |
| `envFlagsProvider(env?, prefix?)` | `FLAG_*` env variables | The variable is unset, or can't be read as the flag's type. |
| `percentageFlagsProvider(shares, salt?)` | A stable share of user ids | The flag is not in `shares`. |
| `staticFlagsProvider(values)` | A map, or a function of the context | The map has no entry for the flag. |
| `openFeatureFlagsProvider(client, flags)` | Any OpenFeature client | Never: the client returns its own default. |
### Env variables
Built in; nothing to install. Good for turning a flag on per environment, or forcing it in staging:
```ts
// config/flags.ts
import { defineConfig, envFlagsProvider } from '@kitr/flags'
import { flags } from '#app/flags'
export default defineConfig({
definitions: flags,
providers: [envFlagsProvider()],
})
```
```sh
FLAG_NEW_DASHBOARD=true
FLAG_MAX_UPLOAD_MB=25
```
Pass a map as the first argument to read from somewhere other than `process.env`, and a prefix as the second: `envFlagsProvider(process.env, 'ACME_FLAG_')` reads `ACME_FLAG_NEW_DASHBOARD`. Changing an env variable needs a server restart.
### Percentage rollout
Built in. Turns a flag on for a share of users, from 0 to 100:
```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, percentageFlagsProvider } from '@kitr/flags'
import { flags } from '#app/flags'
export default defineConfig({
definitions: flags,
providers: [envFlagsProvider(), percentageFlagsProvider({ 'new-dashboard': 25 }, 'dashboard-2026')],
})
```
The answer is a hash of the salt, the flag key and the user id, so Ada gets the same answer on every request and every server. Raising 25 to 50 keeps everyone who already had the feature and adds more. Two flags at 50% reach different, independent halves of your users. Change the salt to draw a new sample.
With no `userId` in the context, the provider answers `false`, and since that is an answer, providers after it are not asked. Put overrides such as `envFlagsProvider()` before it.
### Static rules
Built in. A fixed map, or a function of the context for rules you write in code:
```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, staticFlagsProvider } from '@kitr/flags'
import { flags } from '#app/flags'
export default defineConfig({
definitions: flags,
providers: [
envFlagsProvider(),
staticFlagsProvider((context) => ({
'new-dashboard': context.teamId === 'design',
'max-upload-mb': context.plan === 'pro' ? 100 : undefined,
})),
],
})
```
The design team sees the new dashboard. Pro teams get 100 MB; for everyone else `undefined` means "no opinion", so the default of 10 answers. The context holds `userId` plus whatever you passed to `resolveFlags` or `resolve`.
### OpenFeature
Connect any vendor that has an [OpenFeature provider](https://openfeature.dev/ecosystem): LaunchDarkly, Flagsmith, Unleash, GrowthBook, ConfigCat and others. Install the SDK for the side you resolve on, plus your vendor's provider:
```sh
pnpm add @openfeature/server-sdk
```
```ts
// config/flags.ts
import { InMemoryProvider, OpenFeature } from '@openfeature/server-sdk'
import { defineConfig, envFlagsProvider, openFeatureFlagsProvider } from '@kitr/flags'
import { flags } from '#app/flags'
// Replace InMemoryProvider with your vendor's provider, configured with its SDK key.
OpenFeature.setProvider(
new InMemoryProvider({
'new-dashboard': { variants: { on: true, off: false }, defaultVariant: 'on', disabled: false },
}),
)
export default defineConfig({
definitions: flags,
providers: [envFlagsProvider(), openFeatureFlagsProvider(OpenFeature.getClient(), flags)],
})
```
The adapter calls `getBooleanValue`, `getNumberValue` or `getStringValue` depending on each flag's declared default, passing the default and the context with `targetingKey` set to `userId`. Your vendor's key goes in `.env` as the vendor's docs say, for example `LAUNCHDARKLY_SDK_KEY=sdk-...`. Because an OpenFeature client always answers (with the default when it has no rule), put it last.
## Values a provider can return
Providers often answer with strings, from env files or remote JSON. Each answer is coerced to the flag's declared type; an answer that can't be read as that type counts as no answer, and the next provider is asked:
| Declared type | Accepted answers | Ignored answers |
| --- | --- | --- |
| `boolean` | `true`/`false`; `'true'`, `'1'`, `'on'`, `'yes'`; `'false'`, `'0'`, `'off'`, `'no'`, `''`; numbers (0 is false) | `'maybe'` |
| `number` | Numbers; strings that parse to a finite number, such as `' 7.5 '` | `'lots'`, `''`, `'12px'`, `'Infinity'`, booleans |
| `string` | Strings; numbers and booleans, turned into strings | None |
```ts
// scripts/coercion_demo.ts
import { createFlags, envFlagsProvider, staticFlagsProvider } from '@kitr/flags'
import { flags } from '#app/flags'
const demo = createFlags(flags, {
providers: [
envFlagsProvider({ FLAG_NEW_DASHBOARD: 'yes', FLAG_MAX_UPLOAD_MB: 'lots' }),
staticFlagsProvider({ 'max-upload-mb': 50 }),
],
})
await demo.resolve()
// => { 'new-dashboard': true, 'max-upload-mb': 50, 'invoice-layout': 'classic' }
```
`'lots'` is not a number, so the env provider's answer is ignored and the static provider's `50` wins.
## Retire a flag
A flag is finished when the feature has shipped to everyone. Delete it from `app/flags.ts`:
```ts
// app/flags.ts
import { defineFlags } from '@kitr/flags'
export const flags = defineFlags({
'max-upload-mb': { default: 10, description: 'Largest invoice PDF a team may upload' },
'invoice-layout': { default: 'classic', description: "'classic' or 'compact' invoice PDFs" },
})
```
Every typed `useFlag` and `resolveFlags` read of it is now a type error, which lists the code to clean up. Remove the old branch, then the `FLAG_NEW_DASHBOARD` line and the `'new-dashboard'` share in `config/flags.ts`.
## Testing
`createFlags(definitions, config)` builds a flags service with no app. Give it a `staticFlagsProvider` to test both sides of a flag:
```ts
// app/lib/invoices/validate-upload.test.ts
import { createFlags, staticFlagsProvider } from '@kitr/flags'
import { describe, expect, it } from 'vitest'
import { flags } from '#app/flags'
describe('upload limit flag', () => {
it('answers the default until resolved, then the provider', async () => {
const service = createFlags(flags, { providers: [staticFlagsProvider({ 'max-upload-mb': 25 })] })
expect(service.value('max-upload-mb')).toBe(10)
expect(service.resolved).toBe(false)
expect(await service.resolve({ userId: 'ada' })).toEqual({
'new-dashboard': false,
'max-upload-mb': 25,
'invoice-layout': 'classic',
})
expect(service.value('max-upload-mb')).toBe(25)
})
it('targets by context', async () => {
const service = createFlags(flags, {
providers: [staticFlagsProvider((ctx) => ({ 'new-dashboard': ctx.userId === 'grace' }))],
})
expect((await service.resolve({ userId: 'grace' }))['new-dashboard']).toBe(true)
expect((await service.resolve({ userId: 'linus' }))['new-dashboard']).toBe(false)
})
})
```
To render a component with a flag set, boot a client app with the flags provider and render it with `renderWithKitr` from [testing](/packages/testing). The provider resolves at boot on the client, so the first render already has the value:
```tsx
// app/components/dashboard/dashboard-page.test.tsx
import { defineConfig, staticFlagsProvider } from '@kitr/flags'
import flagsProvider from '@kitr/flags/provider'
import { createTestApp } from '@kitr/testing'
import { renderWithKitr } from '@kitr/testing/react'
import { screen } from '@testing-library/react'
import { expect, it } from 'vitest'
import { flags } from '#app/flags'
import { DashboardPage } from './dashboard-page'
// NewDashboard renders Your new dashboard
.
it('shows the new dashboard when the flag is on', async () => {
const app = await createTestApp({
environment: 'client',
providers: [flagsProvider],
config: {
flags: defineConfig({ definitions: flags, providers: [staticFlagsProvider({ 'new-dashboard': true })] }),
},
})
renderWithKitr(, { app })
expect(screen.getByRole('heading', { name: 'Your new dashboard' })).toBeTruthy()
})
```
Pass `environment: 'client'`. In the default `test` environment the provider does not resolve at boot, and the root app does not keep a resolved snapshot, as on the server.
To flip a flag mid-test, call `app.container.use('flags').hydrate({ 'new-dashboard': false })` inside `act()`; subscribed components re-render.
## Extend
A provider is an object with a `name`, an optional `init(context)` and `resolve(key, context)`:
| Member | Called | Returns |
| --- | --- | --- |
| `name` | In warnings | A label, such as `database`. |
| `init(context)` | Once per `resolve()`, before any key | Nothing. A throw skips the provider for this resolve. |
| `resolve(key, context)` | Once per declared flag | A value, or `undefined` for "no opinion". May be async. |
`init` is the place to load everything a provider needs for one context in a single request, so `resolve` can answer from memory. This provider reads per-team overrides that Acme's support staff publish as JSON at `https://flags.acme.com/teams/.json`:
```ts
// app/flag_providers/team_overrides.ts
import type { FlagsProvider, FlagValue } from '@kitr/flags'
/** Overrides by team, from https://flags.acme.com/teams/.json: { "new-dashboard": true }. */
export function teamOverridesProvider(baseUrl = 'https://flags.acme.com/teams'): FlagsProvider {
const byTeam = new Map>()
return {
name: 'team-overrides',
async init(context) {
const teamId = context.teamId as string | undefined
if (!teamId || byTeam.has(teamId)) return
const response = await fetch(`${baseUrl}/${encodeURIComponent(teamId)}.json`)
if (!response.ok) throw new Error(`flag overrides for ${teamId}: HTTP ${response.status}`)
byTeam.set(teamId, (await response.json()) as Record)
},
resolve(key, context) {
const teamId = context.teamId as string | undefined
return teamId ? byTeam.get(teamId)?.[key] : undefined
},
}
}
```
When the file can't be fetched, `init` throws, the provider is skipped for that resolve with a warning, and the next provider answers. This sketch keeps loaded teams for the life of the process; clear `byTeam` on a timer when overrides must change without a restart. Register the provider in priority order:
```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, percentageFlagsProvider } from '@kitr/flags'
import { flags } from '#app/flags'
import { teamOverridesProvider } from '#app/flag_providers/team_overrides'
export default defineConfig({
definitions: flags,
providers: [envFlagsProvider(), teamOverridesProvider(), percentageFlagsProvider({ 'new-dashboard': 10 })],
})
```
The same config runs in the browser, which is why this provider uses `fetch` and an absolute URL rather than a database client. Keep server-only imports out of `config/flags.ts`. See [`FlagsProvider`](/packages/flags/api#flagsprovider) in the API reference.
## Devtools
When the [devtools](/packages/devtools) package is installed, every resolve or hydrate that updates the snapshot logs `resolved` with all values to the `flags` channel. It shows which values the browser booted with, and whether they came from the server's tag.
## Next steps
- [API reference](/packages/flags/api): every export with its signature.
- [OpenFeature](https://openfeature.dev/docs/reference/intro): the vendor-neutral flag standard the adapter speaks.
- [Auth](/packages/auth): the signed-in user whose id targets rollouts.
- [Cache](/packages/cache): remember slow server reads between requests.
- [Configuration](/docs/configuration): how `config/flags.ts` is loaded.