npm package) is a feature flags toolkit for Next.js and SvelteKit. It turns each feature flag into a callable function, works with any flag provider via adapters, and keeps pages static using the precompute pattern.
Docs:
https://flags-sdk.dev
Repo:
https://github.com/vercel/flags
Core Concepts
Flags as Code
Each flag is declared as a function — no string keys at call sites:
import
{
flag
}
from
'flags/next'
;
export
const
exampleFlag
=
flag
(
{
key
:
'example-flag'
,
decide
(
)
{
return
false
;
}
,
}
)
;
// Usage: just call the function
const
value
=
await
exampleFlag
(
)
;
Server-Side Evaluation
Evaluate flags server-side to avoid layout shift, keep pages static, and maintain confidentiality. Use routing middleware + precompute to serve static variants from CDN.
Adapter Pattern
Adapters replace
decide
and
origin
on a flag declaration, enabling provider-agnostic flags:
import
{
flag
}
from
'flags/next'
;
import
{
statsigAdapter
}
from
'@flags-sdk/statsig'
;
export
const
myGate
=
flag
(
{
key
:
'my_gate'
,
adapter
:
statsigAdapter
.
featureGate
(
(
gate
)
=>
gate
.
value
)
,
identify
,
}
)
;
Declaring Flags
Basic Flag
import
{
flag
}
from
'flags/next'
;
// or 'flags/sveltekit'
export
const
showBanner
=
flag
<
boolean
>
(
{
key
:
'show-banner'
,
description
:
'Show promotional banner'
,
defaultValue
:
false
,
options
:
[
{
value
:
false
,
label
:
'Hide'
}
,
{
value
:
true
,
label
:
'Show'
}
,
]
,
decide
(
)
{
return
false
;
}
,
}
)
;
Flag with Evaluation Context
Use
identify
to establish who the request is for;
decide
receives the entities:
import
{
dedupe
,
flag
}
from
'flags/next'
;
import
type
{
ReadonlyRequestCookies
}
from
'flags'
;
interface
Entities
{
user
?
:
{
id
:
string
}
;
}
const
identify
=
dedupe
(
(
{
cookies
}
:
{
cookies
:
ReadonlyRequestCookies
}
)
:
Entities
=>
{
const
userId
=
cookies
.
get
(
'user-id'
)
?.
value
;
return
{
user
:
userId
?
{
id
:
userId
}
:
undefined
}
;
}
,
)
;
export
const
dashboardFlag
=
flag
<
boolean
,
Entities
>
(
{
key
:
'new-dashboard'
,
identify
,
decide
(
{
entities
}
)
{
if
(
!
entities
?.
user
)
return
false
;
return
[
'user1'
,
'user2'
]
.
includes
(
entities
.
user
.
id
)
;
}
,
}
)
;
Flag with Adapter
import
{
flag
}
from
'flags/next'
;
import
{
vercelAdapter
}
from
'@flags-sdk/vercel'
;
export
const
exampleFlag
=
flag
(
{
key
:
'example-flag'
,
adapter
:
vercelAdapter
(
)
,
}
)
;
Key Parameters
Parameter
Type
Description
key
string
Unique flag identifier
decide
function
Resolves the flag value
defaultValue
any
Fallback if
decide
returns undefined or throws
description
string
Shown in Flags Explorer
origin
string
URL to manage the flag in provider dashboard
options
{ label?: string, value: any }[]
Possible values, used for precompute + Flags Explorer
adapter
Adapter
Provider adapter implementing
decide
and
origin
identify
function
Returns evaluation context (entities) for
decide
Dedupe
Wrap shared functions (especially
identify
) in
dedupe
to run them once per request:
import
{
dedupe
}
from
'flags/next'
;
const
identify
=
dedupe
(
(
{
cookies
}
)
=>
{
return
{
user
:
{
id
:
cookies
.
get
(
'uid'
)
?.
value
}
}
;
}
)
;
Note:
dedupe
is not available in Pages Router.
Flags Explorer Setup
Next.js (App Router)
// app/.well-known/vercel/flags/route.ts
import
{
getProviderData
,
createFlagsDiscoveryEndpoint
}
from
'flags/next'
;
import
*
as
flags
from
'../../../../flags'
;
export
const
GET
=
createFlagsDiscoveryEndpoint
(
async
(
)
=>
{
return
getProviderData
(
flags
)
;
}
)
;
With External Provider Data
import
{
getProviderData
,
createFlagsDiscoveryEndpoint
}
from
'flags/next'
;
import
{
getProviderData
as
getStatsigProviderData
}
from
'@flags-sdk/statsig'
;
import
{
mergeProviderData
}
from
'flags'
;
import
*
as
flags
from
'../../../../flags'
;
export
const
GET
=
createFlagsDiscoveryEndpoint
(
async
(
)
=>
{
return
mergeProviderData
(
[
getProviderData
(
flags
)
,
getStatsigProviderData
(
{
consoleApiKey
:
process
.
env
.
STATSIG_CONSOLE_API_KEY
,
projectId
:
process
.
env
.
STATSIG_PROJECT_ID
,
}
)
,
]
)
;
}
)
;
SvelteKit
// src/hooks.server.ts
import
{
createHandle
}
from
'flags/sveltekit'
;
import
{
FLAGS_SECRET
}
from
'$env/static/private'
;
import
*
as
flags
from
'$lib/flags'
;
export
const
handle
=
createHandle
(
{
secret
:
FLAGS_SECRET
,
flags
}
)
;
FLAGS_SECRET
Required for precompute and Flags Explorer. Must be 32 random bytes, base64-encoded:
Use precompute to keep pages static while using feature flags. Middleware evaluates flags and encodes results into the URL via rewrite. The page reads precomputed values instead of re-evaluating.
High-level flow:
Declare flags and group them in an array
Call
precompute(flagGroup)
in middleware, get a
code
string
Rewrite request to
/${code}/original-path
Page reads flag values from
code
:
await myFlag(code, flagGroup)
For full implementation details, see framework-specific references:
Next.js
See
references/nextjs.md
— covers proxy middleware, precompute setup, ISR, generatePermutations, multiple groups