Docs / Getting started / Local development

Local development

Your app runs on localhost while the auth Worker, D1, KV, and R2 it talks to are real Cloudflare resources on your account. There's no local mock of the backend yet — you develop against a live (but isolated) project. Here's the honest current setup, the sharp edges, and what's coming.

Use a separate dev project

Provision a second project (e.g. myapp-dev) and point your local app at its FLARELINK_AUTH_URL and FLARELINK_SERVICE_KEY. Keep it separate from production so local experiments — schema changes, test signups, deleting rows — never touch real users. Each project is its own D1 + KV + auth Worker, so they're fully isolated.

Add your localhost as a trusted origin

The auth Worker rejects any request whose Origin isn't in its trusted-origins list (403 MISSING_OR_NULL_ORIGIN). Add your local origin — the exact scheme + host + port — in the dev project's Auth panel:

# whatever your dev server actually serves on:
https://localhost:5173
http://localhost:3000

Add every port you use. http://localhost:3000 and https://localhost:5173 are different origins — list each one you develop on.

Serve localhost over HTTPS (Safari needs it)

The session cookie is Secure. Safari refuses to store a Secure cookie over http://localhost (Chrome makes a localhost exception; Safari doesn't), so sign-in appears to succeed but getMe() keeps returning null. The fix is to serve your dev server over HTTPS locally. With Vite:

// vite.config.ts
import mkcert from "vite-plugin-mkcert"

export default {
  plugins: [mkcert()],          // serves https://localhost:5173 with a trusted local cert
}

Then trust https://localhost:5173 in the Auth panel. Chrome users can usually get away with plain http://localhost, but standardising on HTTPS locally avoids a class of "works in Chrome, broken in Safari" bugs. The official starter ships this configured. Full cookie rationale: Cookies & Safari.

Avoid cross-site cookies in dev too

If your local app is on localhost:5173 and the auth Worker is on *.workers.dev, the session cookie is cross-site even locally — same third-party-cookie problem as production. The starter solves this by reverse-proxying /api/auth/* from the dev server to the auth Worker, so the cookie is first-party to localhost. If you're not using the starter, either proxy auth requests through your own dev server or accept that Safari local sign-in won't work until you do.

Current limitations

No offline / fully-local backend. You develop against a live dev project; you need network + a provisioned project. A wrangler dev / Miniflare local-mode story is planned but not shipped.
Shared D1 with auth tables. Your tables live alongside user / account / verification / flarelink_config in the project's D1. Don't reuse those names — see Your schema & migrations.
Email flows need email configured on the dev project (verification, magic link, reset). Use Resend with a test domain for the fastest setup.

Planned

First-class environments (dev/staging/prod per project) and a local-mode that runs the auth Worker + D1 under wrangler dev / Miniflare are on the roadmap. Until then, the dev-project pattern above is the supported path. If local DX is blocking you, tell us — hello@flarelink.dev.

Something unclear or missing? hello@flarelink.dev llms-full.txt ↗