Quickstart
Your first signup on a waitlist in about five minutes.
Goal: your first signup on a waitlist in about five minutes. The commands in
blocks marked bash quickstart are the ones bun run ttfs:measure runs, so
this page stays honest.
You need Bun 1.3+ (or Node 18+ with npm; swap the commands).
Pre-release note.
@getwait/waitlistis not on npm yet. Until it is, build the tarball from the repository (bun run sdk:build && cd packages/getwait-sdk && bun pm pack) and install that file instead of the package name. Everything else is identical.
1. Account and project
Open the dashboard and sign in with your email. You get a magic link, no password. Create a project (it holds your keys, waitlists and webhooks).
2. API keys
A project has two kinds of key (concepts):
- Secret
gw_sk_...: servers only. Can do everything. - Publishable
gw_pk_...: browsers. Can only join and look up status, and only from origins you list.
Create them in the dashboard (project page, "Create API key"). A key is shown once. Put the secret key in your environment:
export GETWAIT_SECRET_KEY=gw_sk_test_...
3. Install the SDK
mkdir getwait-hello && cd getwait-hello
bun init -y
bun add @getwait/waitlist
4. First join
This creates a waitlist and adds one person to it. Save as join.ts:
cat > join.ts <<'TS'
import { createClient } from "@getwait/waitlist"
const client = createClient({
apiKey: process.env.GETWAIT_SECRET_KEY!,
})
const waitlist = await client.waitlists.create({ name: "Quickstart" })
const joined = await client
.waitlist(waitlist.id)
.join({ email: "hello@gmail.com" })
console.log({ waitlistId: waitlist.id, ...joined })
TS
bun join.ts
You should see something like:
{ waitlistId: "01a1...", id: "01a1...", position: 1, referralCode: "YUJZ6KTD", status: "pending", created: true }
position: 1 is the first place on the list. status: "pending" means the
confirmation email is waiting to be clicked (double opt-in is on by default).
Run it again: created is false and nothing new is stored, because joining
is idempotent by email.
Use an address whose domain has a mail server. example.com has none (RFC
7505 null MX), so joins with it are refused with abuse_blocked, as are
disposable-mail domains (see anti-abuse). The check needs DNS
access.
5. See it
Open the project page in the dashboard: the signup is in the signups table, with an export link. Or ask the API:
curl -H "Authorization: Bearer $GETWAIT_SECRET_KEY" \
"https://getwait.dev/api/v1/waitlists/<waitlistId>/signups"
6. Put the form in a browser
Use the publishable key, which is safe in client code, and list your site in its allowed origins. The headless React hook gives you state; you bring the markup:
bun add @getwait/react @getwait/waitlist react
import { useWaitlist, WaitlistProvider } from "@getwait/react"
;<WaitlistProvider publishableKey="gw_pk_..." waitlistId="WAITLIST_ID">
<Form />
</WaitlistProvider>
A complete, runnable version is in examples/nextjs.
Details: packages/react.
Next
- Concepts: position, referrals, double opt-in.
- Webhooks: get each signup pushed to your system.
- Production checklist before you go live.
- API reference for every route.
Measuring this page
bun run ttfs:measure follows steps 3 and 4 literally in a clean temporary
directory (with a freshly created project and the locally packed SDK) and
prints the elapsed seconds. The target is under 300.