Quickstart

Overview

Maya is wiring feature flags into Fieldkit’s web-app. In this guide she creates a boolean toggle called new-checkout, syncs it to production, and evaluates it in a Node process. Time: a few minutes. You need Node.js 20+ and a shipd account.

1. Install the CLI

pnpm add -g @shipdit/cli
shipd --help

2. Log in

shipd login

The CLI opens /auth/device/code. Pick organization → project → environment (Maya picks fieldkit → web-app → production). Approval stores a management API key in ~/.config/shipd/credentials.json.

shipd whoami

CI does not use shipd login. Create a management API key in the dashboard and set SHIPD_API_KEY. See Push flags from CI.

3. Define the flag

Create shipd.config.ts next to package.json:

shipd.config.ts

import { defineFlags } from "shipdit/config";

export default defineFlags({
  "new-checkout": {
    type: "boolean",
    default: false,
    description: "Redesigned checkout flow",
    tags: ["checkout"],
  },
});

shipdit is the SDK package. defineFlags lives at shipdit/config.

4. Push and generate types

shipd push --project web-app --env production --yes

shipd push diffs local definitions against the server, applies them, then writes src/generated/flags.ts.

Plan:
  + create flag "new-checkout"

Wrote types for 1 flag(s) to src/generated/flags.ts

Creating or updating a definition (type, variants, tags, lifecycle) needs production permission even when --env is staging. Defaults are per environment. See Environments.

5. Evaluate it

pnpm add shipdit

src/checkout.ts

import { createClient } from "shipdit";
import type { FlagDefinitions } from "./generated/flags";

const shipd = createClient<FlagDefinitions>({
  sdkKey: process.env.SHIPD_SDK_KEY!,
  endpoint: "https://edge.useshipd.com",
  defaults: { "new-checkout": false },
});

await shipd.ready();

export function checkoutEnabled(userId: string) {
  return shipd.isEnabled("new-checkout", { userId });
}

Create the SDK key in the dashboard (sdkKey.create). Server keys look like shipd_sdk_server_…. The secret is shown once. A misspelled key is a TypeScript error:

shipd.isEnabled("new-chekcout");
//              ^^^^^^^^^^^^^^^ not a BooleanFlagKey

Define more flags

Variants, numbers, JSON — still in shipd.config.ts.

Evaluate in the browser

shipdit/client, polling, and WebSocket invalidation.

Target a user

identify, traits, and userId.

React

ShipdProvider + useFlag.

Getting started

Guides

How-to

Concepts

Reference

Overview

1. Install the CLI

2. Log in

3. Define the flag

4. Push and generate types

5. Evaluate it

Next

Define more flags

Evaluate in the browser

Target a user

React

​Overview

​1. Install the CLI

​2. Log in

​3. Define the flag

​4. Push and generate types

​5. Evaluate it

​Next

Define more flags

Evaluate in the browser

Target a user

React

Overview

1. Install the CLI

2. Log in

3. Define the flag

4. Push and generate types

5. Evaluate it

Next