A Cloudflare-first B2B SaaS starter
Workspaces, auth, REST + MCP, webhooks, email, audit, and admin, typed end-to-end and proven by a working reference app. It boots locally with zero provider secrets.
vp installpnpm run db:migrate:localpnpm run db:seedpnpm run devThe same read that filled the numbers above, followed from the curl that starts it to the binding that persists it. Every excerpt below is real code from this repository; the caption on each panel is its path. In the rail, the node under discussion lights as you read.
curl / SDK
An ordinary bearer-authenticated GET. The body printed below is the live overview this page rendered its numbers from, not a fixture: the first notification is shown in full and the rest are counted, never paraphrased.
curl -H "Authorization: Bearer bsk_live_xxx" \
https://api.example.com/workspaces/starter-lab/overview
{
"workspace": {
"id": "wrk_starter",
"slug": "starter-lab",
"name": "Starter Lab",
"planId": "team"
},
"notifications": []
}apps/api
The route exists because the contract says it does. Path, params, success schema, and the typed error channel sit in one declaration: WORKSPACE_ERRORS is WorkspaceNotFound, Unauthorized, AuthorizationDenied, RateLimited, CapabilityUnavailable — encoded on the endpoint, not thrown as strings. The bearer gate rides the group, so a sibling endpoint cannot ship without it.
export const WorkspaceApi = HttpApiGroup.make('workspace')
.add(
HttpApiEndpoint.get('overview', '/workspaces/:slug/overview', {
params: SlugParams,
success: WorkspaceOverviewDto,
error: WORKSPACE_ERRORS
})
)
.middleware(BearerAuth)packages/capabilities
Both surfaces call the same effect. Its failure channel and its service requirements are part of its type, so every caller shares one failure vocabulary and the compiler checks the wiring — the claim on this page that cannot be faked.
export const workspaceOverview: Effect.Effect<
WorkspaceOverviewProjection,
CapabilityUnavailable,
WorkspaceContext | NotificationFeed
> = Effect.gen(function* () {
const ctx = yield* WorkspaceContext
const feed = yield* NotificationFeed
const notifications = yield* feed.list
return {
workspace: ctx.workspace,
notifications
}
})return runWorkspaceCapabilities(
DEMO_WORKSPACE_SLUG,
Effect.all({ overview: workspaceOverview, memberCount: … })
).handle('overview', ({ params, request }) =>
workspaceRead(READ_OPERATIONS.overview, params, undefined, request)
)const invoke = yield* decodeOperationInput(operation, payload)
yield* requirePermission(yield* callerPrincipal(caller), operation.permission)
return yield* invokeD1 · Queues · Email
Every binding below the effect is declared once in alchemy.run.ts: the same TypeScript description provisions local dev and production, so the whole story ends in pnpm run deploy.
| binding | what it holds | declared in |
|---|---|---|
| D1 | SQLite: schema, migrations, seed rows | packages/db |
| Queues | Webhook deliveries with retries and backoff | apps/background |
| Transactional sends, provider-gated until configured | packages/email |
The lit node follows the stage.
Stripe, Sentry, PostHog, Cloudflare Email, and Turnstile ship with real integrations that stay inactive until their env vars exist. Local development never blocks on a provider account.
Stripe
Billing checkout, portal, and webhooks
env-gated
Sentry
Error monitoring across all three Workers
env-gated
PostHog
Product analytics — browser and all three Workers
env-gated
Cloudflare Email
Outbound transactional email
env-gated
Turnstile
Bot protection on public forms
env-gated
Docs, FAQ, and blog are versioned MDX in the repo, searched from generated indexes, no CMS. The blog explains why each technology call was made, and releases are cut by release-please.
docs/
MIT licensed. The reference application runs locally against a seed workspace: no Stripe key, no OAuth app, no email domain required.
clone and quickstart