Skip to content

Interactive Setup

This page is your one place to get your app running. No technical knowledge needed. Everything you need is right here, from first setup to the final deploy.

The setup wizard (pnpm run setup) walks through the required steps directly in your terminal. This page is here as a reference when you want to review what each setup check means.

Checking local setup…

When setup is finished

Section titled “When setup is finished”

When every required check is done, the bottom-right helper will show this command:

Terminal window
pnpm setup:complete

Run it from your terminal to hide the helper on this machine. If you ever want the helper back, remove SETUP_GUIDE_HIDDEN=true from .env and restart pnpm dev.

How to read this page

Section titled “How to read this page”

Start at the top and work down. Each section shows you what is working and what still needs attention. Click any action button to fix it, then refresh the page. No searching through docs required.

You do not need to memorize anything. Fix the first missing item, refresh the page, and keep going until the helper says everything required is ready.

What this checks

Section titled “What this checks”

The checklist has five sections. Each section runs live checks against your local .env file and the services you connect. Green means ready, yellow means optional or needs attention, and red means something is missing.

1. Cloudflare hosting and database

This is where your app lives on the internet and where your data is stored. Cloudflare hosts your site, and the D1 database keeps your users, posts, and everything else saved.

The checklist checks:

  • D1 database ID — set CLOUDFLARE_D1_DATABASE_ID in .env. The setup wizard creates your database and fills this in automatically.
  • API token — shown when CLOUDFLARE_API_TOKEN is set. The checklist verifies the token has Workers and D1 access so the deploy tools can push your app.
  • D1 API access — shown when your account, database, and token are all configured. Verifies Cloudflare can actually read the database.
  • Production secrets — shown only when the checklist can list Worker secrets and compare them. OAuth sign-in (wrangler login) cannot always list secrets, so this row stays hidden when the check is unavailable.
  • Production Worker — shown when SITE_URL or BETTER_AUTH_URL points at a non-localhost URL. Verifies your deployed app is responding.

The setup wizard handles Cloudflare sign-in, account selection, and database creation. Just run pnpm run setup and follow the prompts.

Before you deploy, set BETTER_AUTH_URL in .env:

  • Local dev: BETTER_AUTH_URL=http://localhost:4321
  • Production: BETTER_AUTH_URL=https://your-domain.com (or your .workers.dev URL)

This tells the login system which address it is running at. The deploy step (pnpm setup:deploy) sets this automatically for production.

2. Login system

This is your login system. It lets people create accounts and sign in to your app with an email address and password.

The checklist checks three things:

  • Auth secret (BETTER_AUTH_SECRET) — the key that keeps user sessions secure. The setup wizard generates a 32-byte secret and writes it to .env.
  • Runtime URL (SITE_URL or BETTER_AUTH_URL) — tells the login system which address it is running at. Set this to http://localhost:4321 for local dev, or your production domain after deploying.
  • D1 binding (DB) — verifies the dev server is running and the database is connected. Start with pnpm dev.

When all three are ready, use the Test login button to open the auth playground and try signing up locally.

3. Sign in with Google

Sign in with Google lets people use their Google account instead of creating a new password.

If you have not set any Google settings yet, the checklist shows one warning: “Optional. Skip this unless you want users to sign in with Google.” This is normal and not a problem.

Once you add GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET, the checklist shows individual checks for each. Both must be set for Google sign-in to work. Add http://localhost:4321/api/auth/callback/google as a local authorized redirect URI in Google Cloud Console, then test the flow in the auth playground.

The redirect URI is just the address Google sends you back to after sign-in. Copy it exactly; small typos are the most common problem.

4. Email delivery

Email delivery lets your app send password reset links, welcome emails, and login codes. It is optional for basic email and password login but required for features like password reset, email verification, and magic links.

If you have not set any Resend settings yet, the checklist shows one warning: “Optional. Skip this unless you need password resets, verification emails, or login codes.”

Once you add RESEND_API_KEY or RESEND_FROM_EMAIL, the checklist shows individual checks for each. When both are set and your API key is valid, the checklist also verifies your domain against the Resend API. Use an email address from a verified domain, like Your App <hello@example.com>.

5. Polar payments

Payments let customers buy your product. Polar checks are always optional — they show yellow (warning) instead of red (missing) when you skip them.

The checklist checks:

  • Product ID (POLAR_PRODUCT_ID) — for a simple checkout button, this is all you need. Customers are sent straight to a Polar checkout page.
  • Access token (POLAR_ACCESS_TOKEN) — for server-side payment features like checkout sessions. When set, the checklist verifies the token against the Polar API.
  • API handshake — shown when the access token is present. Confirms Polar accepted the token and your organization is accessible.

If you only need a checkout button, a product ID is enough. The access token is for more advanced server-side features like creating checkout sessions from your own API.