Quickstart — Shoal

This guide takes about five minutes. You need Node.js 18 or newer and a Shoal account.

Create a project

In the dashboard, click New project and give it a name. Shoal creates two environments for you — development and production — each with its own SDK key.

Install the SDK

Terminal

npm install @shoal/sdk

Terminal

pnpm add @shoal/sdk

Terminal

yarn add @shoal/sdk

Terminal

bun add @shoal/sdk

Add your key

Copy the server key for development from Project settings → Keys and add it to your environment:
.env.local
```
SHOAL_KEY=sk_dev_7f3a9c1e5b2d
```

Create a flag

Create a boolean flag called new-checkout in the dashboard, or from your terminal:

Terminal

npx shoal flags create new-checkout --type boolean

Terminal

pnpm dlx shoal flags create new-checkout --type boolean

Terminal

yarn dlx shoal flags create new-checkout --type boolean

Terminal

bunx shoal flags create new-checkout --type boolean

Evaluate it

checkout.ts

import { createClient } from "@shoal/sdk";

const shoal = createClient({ key: process.env.SHOAL_KEY! });

export async function checkoutVariant(userId: string) {
  const on = await shoal.isOn("new-checkout", { user: { id: userId } });
  return on ? "new" : "classic";
}

Toggle the flag in the dashboard and call the function again — the result changes without a restart.

Next steps

Targeting rulesTurn a flag on for specific users, plans or countries.Gradual rolloutsRelease to 1%, 10%, 50% and watch your metrics.