Getting Started

Run the app locally, understand the key bindings, and know what is public versus protected.

Local development

Use the normal Waku loop for UI work:

npm install
npm run dev

For Worker-local validation with Cloudflare bindings:

npm run preview:worker

If you use Wrangler locally, copy .dev.vars.example to .dev.vars and fill in local-only secret values. Do not commit .dev.vars.

The docs live in this repo and ship with the normal app build, so validation stays simple:

npm run typecheck
npm run build

The app still depends on the same Cloudflare resources:

EMAIL for outbound replies and magic-link sign-in
INBOX_R2 for stored message payloads, attachments, and per-inbox sending settings
SUPPORT_ALIAS as the default mailbox fallback for inbound/default mailbox discovery
INTERNAL_SENDER_EMAIL for internal notifications such as magic-link email
optional INTERNAL_SENDER_NAME for internal notification display name
FORWARDING_ADDRESS

/ is public.
/docs is public.
/login is public.
/app is protected when magic-link auth is configured or when AUTH_REQUIRED=true.

With AUTH_REQUIRED=true, the app fails closed if required auth dependencies are missing instead of silently making /app public.

Configure the Cloudflare bindings first.
Keep AUTH_REQUIRED=true in production-like Wrangler config.
Set AUTH_COOKIE_SECRET as a Worker secret.
Confirm FORWARDING_ADDRESS, SUPPORT_ALIAS, INTERNAL_SENDER_EMAIL, and the EMAIL binding are configured.
Deploy the Worker.
Verify /docs, /login, and /app.
In /app, open inbox settings for each mailbox and configure its sender alias. Leaving the alias blank sends as the bare inbox email address.

Use a dedicated bearer API_TOKEN secret only if you need the machine /api/* routes.