Installation — Shoal

The @shoal/sdk package has no runtime dependencies and ships ESM and CommonJS builds with type definitions.

Terminal

npm install @shoal/sdk

Terminal

pnpm add @shoal/sdk

Terminal

yarn add @shoal/sdk

Terminal

bun add @shoal/sdk

Supported runtimes

Runtime	Minimum version	Notes
Node.js	18	Uses the built-in `fetch`
Bun	1.0
Deno	1.40	Import from `npm:@shoal/sdk`
Browsers	Last 2 versions	Use a client key
Edge (Cloudflare, Vercel, Netlify)	—	Streaming falls back to polling

Framework packages

Thin wrappers add idiomatic helpers on top of the core SDK. Install the one for your framework instead of — not in addition to — the core package when you only need it there.

Terminal

npm install @shoal/react

Terminal

pnpm add @shoal/react

Terminal

yarn add @shoal/react

Terminal

bun add @shoal/react

App.tsx

import { ShoalProvider, useFlag } from "@shoal/react";

function Banner() {
  const on = useFlag("summer-banner");
  return on ? <p>Summer sale — 20% off</p> : null;
}

Terminal

npm install @shoal/next

Terminal

pnpm add @shoal/next

Terminal

yarn add @shoal/next

Terminal

bun add @shoal/next

Read the full Next.js guide for server components and middleware.

Terminal

npm install @shoal/vue

Terminal

pnpm add @shoal/vue

Terminal

yarn add @shoal/vue

Terminal

bun add @shoal/vue

main.ts

import { shoal } from "@shoal/vue";
app.use(shoal, { key: import.meta.env.VITE_SHOAL_CLIENT_KEY });

Generate flag types

The CLI reads your project and writes a type file so flag keys are checked at compile time.

Terminal

npm install -D @shoal/cli

Terminal

pnpm add -D @shoal/cli

Terminal

yarn add -D @shoal/cli

Terminal

bun add -d @shoal/cli

Terminal

npx shoal generate --out src/shoal.d.ts

TypeScript

shoal.isOn("new-chekout");
// ^ Argument of type '"new-chekout"' is not assignable to parameter of type FlagKey