Skip to content

Commit 40fed63

Browse files
vincent-derksvincent-derks
authored
Make cli more prominent in skill (#310)
* Make CLI more prominent in skill * Advertise cli skill more * Removed cli examples duplication
1 parent 2db1530 commit 40fed63

File tree

2 files changed

+211
-45
lines changed

2 files changed

+211
-45
lines changed

‎skills/flags-sdk/SKILL.md‎

Lines changed: 147 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,34 @@
11
---
22
name: flags-sdk
33
description: >
4-
Comprehensive guide for implementing feature flags and A/B tests using the Flags SDK (the `flags` npm package).
5-
Use when: (1) Creating or declaring feature flags with `flag()`, (2) Setting up feature flag providers/adapters
6-
(Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Hypertune, Edge Config, OpenFeature, Flagsmith, Reflag,
7-
Split, Optimizely, or custom adapters), (3) Implementing precompute patterns for static pages with feature flags,
8-
(4) Setting up evaluation context with `identify` and `dedupe`, (5) Integrating the Flags Explorer / Vercel Toolbar,
9-
(6) Working with feature flags in Next.js (App Router, Pages Router, Middleware) or SvelteKit,
10-
(7) Writing custom adapters, (8) Encrypting/decrypting flag values for the toolbar,
11-
(9) Any task involving the `flags`, `flags/next`, `flags/sveltekit`, `flags/react`, or `@flags-sdk/*` packages.
4+
Comprehensive guide for implementing feature flags and A/B tests using the Flags SDK (the `flags` npm package)
5+
and Vercel Flags (Vercel's feature flags platform, managed via dashboard or `vercel flags` CLI).
6+
Use when: (1) Creating or declaring feature flags with `flag()`, (2) Using Vercel Flags with `vercelAdapter()` or
7+
the `vercel flags` CLI (`add`, `list`, `enable`, `disable`, `inspect`, `archive`, `rm`, `sdk-keys`),
8+
(3) Setting up feature flag providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Hypertune,
9+
Edge Config, OpenFeature, Flagsmith, Reflag, Split, Optimizely, or custom adapters),
10+
(4) Implementing precompute patterns for static pages with feature flags,
11+
(5) Setting up evaluation context with `identify` and `dedupe`, (6) Integrating the Flags Explorer / Vercel Toolbar,
12+
(7) Working with feature flags in Next.js (App Router, Pages Router, Middleware) or SvelteKit,
13+
(8) Writing custom adapters, (9) Encrypting/decrypting flag values for the toolbar,
14+
(10) Any task involving the `flags`, `flags/next`, `flags/sveltekit`, `flags/react`, or `@flags-sdk/*` packages.
1215
Triggers on: feature flags, A/B testing, experimentation, flags SDK, flag adapters, precompute flags,
13-
Flags Explorer, feature gates, flag overrides.
16+
Flags Explorer, feature gates, flag overrides, Vercel Flags, vercel flags CLI, vercel flags add,
17+
vercel flags list, vercel flags enable, vercel flags disable.
1418
---
1519

1620
# Flags SDK
1721

18-
The Flags SDK (`flags` 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.
22+
The Flags SDK (`flags` 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. Vercel Flags is the first-party provider, letting you manage flags from the Vercel dashboard or the `vercel flags` CLI.
1923

2024
- Docs: https://flags-sdk.dev
2125
- Repo: https://github.com/vercel/flags
2226

23-
## Core Concepts
27+
## Core concepts
2428

25-
### Flags as Code
29+
### Flags as code
2630

27-
Each flag is declared as a function — no string keys at call sites:
31+
Each flag is declared as a function. No string keys at call sites:
2832

2933
```ts
3034
import { flag } from 'flags/next';
@@ -34,32 +38,132 @@ export const exampleFlag = flag({
3438
decide() { return false; },
3539
});
3640

37-
// Usage: just call the function
3841
const value = await exampleFlag();
3942
```
4043

41-
### Server-Side Evaluation
44+
### Server-side evaluation
4245

43-
Evaluate flags server-side to avoid layout shift, keep pages static, and maintain confidentiality. Use routing middleware + precompute to serve static variants from CDN.
46+
Flags evaluate server-side to avoid layout shift, keep pages static, and maintain confidentiality. Combine routing middleware with the precompute pattern to serve static variants from CDN.
4447

45-
### Adapter Pattern
48+
### Adapter pattern
4649

47-
Adapters replace `decide` and `origin` on a flag declaration, enabling provider-agnostic flags:
50+
Adapters replace `decide` and `origin` on a flag declaration, connecting your flags to a provider. Vercel Flags (`@flags-sdk/vercel`) is the first-party adapter. Third-party adapters are available for Statsig, LaunchDarkly, PostHog, and others.
4851

4952
```ts
5053
import { flag } from 'flags/next';
51-
import { statsigAdapter } from '@flags-sdk/statsig';
54+
import { vercelAdapter } from '@flags-sdk/vercel';
5255

53-
export const myGate = flag({
54-
key: 'my_gate',
55-
adapter: statsigAdapter.featureGate((gate) => gate.value),
56+
export const exampleFlag = flag({
57+
key: 'example-flag',
58+
adapter: vercelAdapter(),
59+
});
60+
```
61+
62+
## Vercel Flags
63+
64+
Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the `vercel flags` CLI, then connect them to your code with the `@flags-sdk/vercel` adapter. When you create a flag in Vercel, the `FLAGS` and `FLAGS_SECRET` environment variables are configured automatically.
65+
66+
### Quickstart
67+
68+
Install the adapter:
69+
70+
```bash
71+
pnpm i flags @flags-sdk/vercel
72+
```
73+
74+
Create a flag in the Vercel dashboard, then pull environment variables:
75+
76+
```bash
77+
vercel env pull
78+
```
79+
80+
You may need to run `vercel link` first if your project isn't linked to Vercel yet.
81+
82+
Declare the flag in your code:
83+
84+
```ts
85+
// flags.ts
86+
import { flag } from 'flags/next';
87+
import { vercelAdapter } from '@flags-sdk/vercel';
88+
89+
export const exampleFlag = flag({
90+
key: 'example-flag',
91+
adapter: vercelAdapter(),
92+
});
93+
```
94+
95+
`vercelAdapter()` reads the `FLAGS` environment variable automatically. Call the flag as a function to resolve its value:
96+
97+
```tsx
98+
// app/page.tsx
99+
import { exampleFlag } from '../flags';
100+
101+
export default async function Page() {
102+
const showExample = await exampleFlag();
103+
return <div>{showExample ? 'Feature enabled' : 'Feature disabled'}</div>;
104+
}
105+
```
106+
107+
Toggle the flag in the Vercel dashboard for any environment (development, preview, production) and reload the page to see the change.
108+
109+
### User targeting
110+
111+
Target specific users or groups by providing an `identify` function. The returned entities are passed to Vercel Flags for rule evaluation:
112+
113+
```ts
114+
import { dedupe, flag } from 'flags/next';
115+
import { vercelAdapter } from '@flags-sdk/vercel';
116+
117+
type Entities = {
118+
team?: { id: string };
119+
user?: { id: string };
120+
};
121+
122+
const identify = dedupe(async (): Promise<Entities> => ({
123+
team: { id: 'team-123' },
124+
user: { id: 'user-456' },
125+
}));
126+
127+
export const exampleFlag = flag<boolean, Entities>({
128+
key: 'example-flag',
56129
identify,
130+
adapter: vercelAdapter(),
57131
});
58132
```
59133

60-
## Declaring Flags
134+
Configure which entity types are available for targeting in the Vercel Flags dashboard under your project's flags settings.
135+
136+
### `vercel flags` CLI
137+
138+
You can manage Vercel Flags from the terminal with `vercel flags`. The CLI supports creating, toggling, inspecting, archiving, and deleting flags, as well as managing SDK keys. It requires the [Vercel CLI](https://vercel.com/docs/cli) and a linked project (`vercel link`).
139+
140+
Available subcommands: `list`, `add`, `inspect`, `enable`, `disable`, `archive`, `rm`, `sdk-keys`.
141+
142+
For detailed examples and all subcommand options, see [references/providers.md](references/providers.md#vercel-flags-cli). For the full Vercel CLI reference (beyond flags), install the `vercel-cli` skill:
143+
144+
```bash
145+
npx skills add https://github.com/vercel/vercel --skill vercel-cli
146+
```
147+
148+
For advanced adapter configuration (custom SDK keys, singleton clients), see [references/providers.md](references/providers.md#vercel).
149+
150+
## Declaring flags
151+
152+
### With Vercel Flags (recommended)
153+
154+
Use `vercelAdapter()` to connect your flag to Vercel Flags. The adapter handles evaluation, so you don't need a `decide` function:
155+
156+
```ts
157+
import { flag } from 'flags/next';
158+
import { vercelAdapter } from '@flags-sdk/vercel';
159+
160+
export const exampleFlag = flag({
161+
key: 'example-flag',
162+
adapter: vercelAdapter(),
163+
});
164+
```
61165

62-
### Basic Flag
166+
### Basic flag
63167

64168
```ts
65169
import { flag } from 'flags/next'; // or 'flags/sveltekit'
@@ -76,9 +180,9 @@ export const showBanner = flag<boolean>({
76180
});
77181
```
78182

79-
### Flag with Evaluation Context
183+
### Flag with evaluation context
80184

81-
Use `identify` to establish who the request is for; `decide` receives the entities:
185+
Use `identify` to establish who the request is for. The returned entities are passed to `decide`:
82186

83187
```ts
84188
import { dedupe, flag } from 'flags/next';
@@ -105,19 +209,24 @@ export const dashboardFlag = flag<boolean, Entities>({
105209
});
106210
```
107211

108-
### Flag with Adapter
212+
### Flag with another adapter
213+
214+
Adapters connect flags to third-party providers. Each adapter replaces `decide` and `origin`:
109215

110216
```ts
111217
import { flag } from 'flags/next';
112-
import { vercelAdapter } from '@flags-sdk/vercel';
218+
import { statsigAdapter } from '@flags-sdk/statsig';
113219

114-
export const exampleFlag = flag({
115-
key: 'example-flag',
116-
adapter: vercelAdapter(),
220+
export const myGate = flag({
221+
key: 'my_gate',
222+
adapter: statsigAdapter.featureGate((gate) => gate.value),
223+
identify,
117224
});
118225
```
119226

120-
### Key Parameters
227+
See [references/providers.md](references/providers.md) for all supported adapters.
228+
229+
### Key parameters
121230

122231
| Parameter | Type | Description |
123232
| -------------- | ---------------------------------- | ---------------------------------------------------- |
@@ -144,7 +253,7 @@ const identify = dedupe(({ cookies }) => {
144253

145254
Note: `dedupe` is not available in Pages Router.
146255

147-
## Flags Explorer Setup
256+
## Flags Explorer setup
148257

149258
### Next.js (App Router)
150259

@@ -158,7 +267,7 @@ export const GET = createFlagsDiscoveryEndpoint(async () => {
158267
});
159268
```
160269

161-
### With External Provider Data
270+
### With external provider data
162271

163272
```ts
164273
import { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next';
@@ -198,7 +307,7 @@ node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
198307

199308
Store as `FLAGS_SECRET` env var. On Vercel: `vc env add FLAGS_SECRET` then `vc env pull`.
200309

201-
## Precompute Pattern (Overview)
310+
## Precompute pattern
202311

203312
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.
204313

@@ -212,7 +321,7 @@ For full implementation details, see framework-specific references:
212321
- **Next.js**: See [references/nextjs.md](references/nextjs.md) — covers proxy middleware, precompute setup, ISR, generatePermutations, multiple groups
213322
- **SvelteKit**: See [references/sveltekit.md](references/sveltekit.md) — covers reroute hook, middleware, precompute setup, ISR, prerendering
214323

215-
## Custom Adapters
324+
## Custom adapters
216325

217326
Create an adapter factory returning an object with `origin` and `decide`:
218327

@@ -234,7 +343,7 @@ export function createMyAdapter(/* options */) {
234343
}
235344
```
236345

237-
## Encryption Functions
346+
## Encryption functions
238347

239348
For keeping flag data confidential in the browser (used by Flags Explorer):
240349

@@ -259,7 +368,7 @@ async function ConfidentialFlags({ values }) {
259368
}
260369
```
261370

262-
## React Components
371+
## React components
263372

264373
```tsx
265374
import { FlagValues, FlagDefinitions } from 'flags/react';

‎skills/flags-sdk/references/providers.md‎

Lines changed: 64 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -107,25 +107,82 @@ export const exampleFlag = flag({
107107
});
108108
```
109109

110-
### CLI
110+
### `vercel flags` CLI
111111

112-
Manage Vercel Flags from the terminal with `vercel flags`. Requires the [Vercel CLI](https://vercel.com/docs/cli) (`pnpm i -g vercel`) and a linked project.
112+
Manage Vercel Flags from the terminal. Requires the [Vercel CLI](https://vercel.com/docs/cli) (`pnpm i -g vercel`) and a linked project (`vercel link`).
113113

114-
Available subcommands: `list`, `add`, `inspect`, `enable`, `disable`, `archive`, `rm`, `sdk-keys`.
114+
#### Subcommands
115+
116+
| Subcommand | Description |
117+
| ------------ | ----------------------------------------------------- |
118+
| `list` | List all flags in the project |
119+
| `add` | Create a new flag |
120+
| `inspect` | Show details, status, and targeting rules of a flag |
121+
| `enable` | Enable a boolean flag for a specific environment |
122+
| `disable` | Disable a boolean flag for a specific environment |
123+
| `archive` | Archive a flag (required before deleting) |
124+
| `rm` | Delete an archived flag |
125+
| `sdk-keys` | Manage SDK keys (subcommands: `ls`, `add`, `rm`) |
126+
127+
#### Create and toggle a flag
115128

116129
```bash
130+
# Create a boolean flag with a description
117131
vercel flags add my-feature --kind boolean --description "New onboarding flow"
132+
133+
# Enable in development first
134+
vercel flags enable my-feature --environment development
135+
136+
# Promote to production
118137
vercel flags enable my-feature --environment production
138+
139+
# Disable in production
140+
vercel flags disable my-feature --environment production
141+
```
142+
143+
`enable` and `disable` only work with boolean flags. For other flag types, configure values in the Vercel dashboard.
144+
145+
#### Inspect and list flags
146+
147+
```bash
148+
# Show details of a specific flag (status, environments, targeting rules)
149+
vercel flags inspect my-feature
150+
151+
# List all flags in the project
119152
vercel flags list
153+
```
154+
155+
#### Archive and delete a flag
156+
157+
A flag must be archived before it can be deleted:
158+
159+
```bash
160+
vercel flags archive my-feature
161+
vercel flags rm my-feature
162+
```
163+
164+
#### Manage SDK keys
165+
166+
SDK keys connect your application to Vercel Flags. The `FLAGS` environment variable contains an SDK key.
167+
168+
```bash
169+
# List SDK keys for the project
120170
vercel flags sdk-keys ls
171+
172+
# Create a new SDK key
173+
vercel flags sdk-keys add
174+
175+
# Remove an SDK key
176+
vercel flags sdk-keys rm <sdk-key-id>
121177
```
122178

123-
`enable` / `disable` only work with boolean flags. A flag must be archived before it can be deleted.
179+
These examples cover common flag operations, but the CLI supports additional commands and options not listed here. For the full `vercel flags` reference and other Vercel CLI commands, install the `vercel-cli` skill:
124180

125-
Full CLI reference: https://vercel.com/docs/cli/flags
181+
```bash
182+
npx skills add https://github.com/vercel/vercel --skill vercel-cli
183+
```
126184

127-
> For broader Vercel CLI usage, install the `vercel-cli` skill:
128-
> `npx skills add https://github.com/vercel/vercel --skill vercel-cli`
185+
Full CLI reference: https://vercel.com/docs/cli/flags
129186

130187
---
131188

0 commit comments

Comments
 (0)