开源AI工作流

Dependency Automation

Renovate groups non-major updates into a single PR and creates separate PRs for packages that tend to ship breaking changes (Better Auth, AI SDK, ESLint), so upgrades are easier to review.

Preview Deployments

Each PR gets its own preview deployment with an isolated Convex preview backend. Supports both Cloudflare Workers and Vercel.

Create a Convex project at dashboard.convex.dev and connect your repo to your hosting platform.

Protect the production branch, require the Lint & Format and English PR Metadata checks, and enable Require branches to be up to date before merging. English PR Metadata checks the pull request title and each prose paragraph in the body. Lint & Format runs the Convex consumer-compatibility guard, and the up-to-date requirement makes its baseline include every change already merged to production. Hosting builds start from a push, so the push-time copy of the check serves as an alarm after an unsupported direct or administrative push and cannot stop a build that already started.

The guard forces the compatibility release for a renamed function. Alias retirement still needs operational evidence: browser bundles can remain open indefinitely, and a scheduled target must remain until every pending runAfter or runAt job carrying its old path has run or been cancelled.

The deploy script (scripts/deploy.ts) auto-detects the platform from environment variables (WORKERS_CI, CF_PAGES, or VERCEL), tags and pulls translations, runs bunx convex deploy to create a preview backend named after the branch, auto-computes PUBLIC_CONVEX_URL and PUBLIC_CONVEX_SITE_URL from the deploy output, and sets SITE_URL on the Convex instance to match the preview URL. It also seeds an admin user (admin@preview.dev) on every preview. Set the password once as a Convex preview default env var, every new preview deployment inherits it regardless of which CI builds it:

bunx convex env default set --type preview PREVIEW_ADMIN_PASSWORD '<password>'

<details> <summary><strong>Cloudflare Workers setup</strong></summary>

Deploy via Cloudflare Workers with Workers Builds:

1. Create Worker

• Rename name in wrangler.toml to your project name
• Run bunx varlock-wrangler deploy (first deploy creates the Worker)

varlock-wrangler is a thin wrapper around wrangler that resolves the env schema and uploads it to the Worker: non-sensitive values become Worker vars, @sensitive ones become Worker secrets, and a __VARLOCK_ENV secret carries the resolved graph that the SSR bundle reads at boot. The Cloudflare build embeds no env in the bundle, so resolved secrets never land in the Worker script (which is API-readable and archived per version). Deploying with plain wrangler would upload a Worker with no env at all. The other adapters (Vercel, adapter-node) have no upload step, so there the resolved env is still serialized into the bundle, with @sensitive values stripped out of it (scripts/strip-varlock-secrets.ts).

2. Connect repo

• CF dashboard > Workers & Pages > select Worker > Builds > Connect
• If the repo isn't visible: GitHub Settings > Applications > Cloudflare Workers and Pages > Configure > grant repo access

3. Configure build commands

4. Add build variables (plain text, visible in logs)

5. Add build secrets (encrypted, hidden from logs)

6. Set Convex default env vars for previews

Each preview Convex deployment starts with no env vars. Set defaults in Convex dashboard > Project Settings > Default Environment Variables with only Preview/Development checked (not Production):

BETTER_AUTH_SECRET, RESEND_API_KEY, AUTH_EMAIL, EMAIL_ASSET_URL, AUTUMN_SECRET_KEY, OPENROUTER_API_KEY

Optionally add AUTH_E2E_TEST_SECRET for E2E tests on previews.

7. Enable branch builds

Enable non-production branch builds for preview deployments. Push a branch and Workers Builds creates a preview deployment with a stable per-branch URL.

</details>

<details> <summary><strong>Vercel setup</strong></summary>

Connect your repo to Vercel. Set the required Vercel and Convex preview variables listed in the environment variable matrix below.

• Vercel: Project Settings > Environment Variables
• Convex: Project settings > Default Environment Variables > Add with ✓ Production

Push a branch and Vercel creates a preview deployment with its own Convex preview backend.

</details>

Production Deployment

Set the required platform and Convex production variables listed in the environment variable matrix below.

• Platform: Project Settings > Environment Variables (CF Workers or Vercel)
• Convex: Select your Prod deployment > Settings > Environment Variables > Add

Deploy

Merge a reviewed pull request into your production branch (default: main) and the connected platform deploys the resulting push. Deployment is push-driven, so whatever the merge puts on that branch becomes the production build. Keeping review in that path is a maintainer procedure; what branch protection enforces is the narrower technical half described under Preview Deployments, that a pull request's required checks passed against an up-to-date branch. Verify or configure those settings separately for each fork, since they live in GitHub rather than in this repository and an organization rule may already supply some of them.

Each supported platform also has a manual deploy:

Cloudflare Workers:

bun scripts/cf-prod-deploy.ts

Vercel:

vercel --prod

<details> <summary><strong>Self-hosted production with Coolify</strong></summary>

Use the existing Cloudflare Workers or Vercel setup for preview deployments, and run production on Coolify when you want a self-hosted Node app with the same Convex cloud backend.

Architecture:

• Previews: Cloudflare Workers or Vercel, using the existing preview deploy flow above
• Production app hosting: Coolify
• Backend/data/auth: Convex cloud production deployment

Coolify setup:

1. Add the repo as an application in Coolify and use the Nixpacks build pack
2. Set the build command to:

bunx varlock run -- bun scripts/deploy.ts

1. Set the start command to:

node build

4. Set app-level environment variables in Coolify: - NODE_ADAPTER=1 - PUBLIC_SITE_URL (the public frontend origin, for canonical URLs in the server build) - CONVEX_DEPLOY_KEY - TOLGEE_API_KEY (optional) - CONVEX_INTERNAL_URL (optional, only if the app container can reach Convex through a private Docker network URL) 5. Set the required Convex production environment variables in the Convex dashboard 6. Set SITE_URL on the Convex production deployment to your public production domain

The build command intentionally reuses scripts/deploy.ts so production stays aligned with the existing deploy flow: Tolgee sync remains optional, Convex is deployed during the build, and PUBLIC_CONVEX_URL / PUBLIC_CONVEX_SITE_URL are computed automatically from the deploy output instead of being copied into Coolify by hand.

</details>

Quick Start

Start the app with a local Convex backend and a seeded admin account:

gh repo create my-saas-product --template stickerdaniel/saas-starter --clone
cd my-saas-product
bun install
bun run dev

Visit the URL printed by bun run dev (a stable per-project port) and sign in:

admin@local.dev

LocalDevAdmin123!

No external services required. To activate optional features (email, OAuth, billing, AI), add keys to .env.convex.local. See the environment variable matrix below.

<details> <summary><strong>What about the Convex cloud dev deployment?</strong></summary>

I'd recommend the local embedded backend for day-to-day work. Each git worktree gets its own isolated Convex instance, you can develop multiple features in parallel without conflicts.

bunx convex dev --configure                   # creates/links a Convex project

convex dev prints a CONVEX_DEPLOYMENT value, add it to .env.local. bun run dev still uses the local embedded backend; the variable is only needed for dev:cloud and the Convex CLI.

bun run dev:cloud                             # frontend + cloud Convex backend
bunx convex env set KEY value                 # set backend env vars (see .env-convex.schema / env matrix below)

</details>

<details> <summary><strong>Optional: stable named URLs with portless</strong></summary>

bun run dev and bun run test:e2e already pick stable per-project ports (derived from the project path in scripts/dev-ports.ts), so several projects or worktrees run at once without clashing. If you'd rather use names than remember ports, vercel-labs/portless fronts the dev server with a .localhost URL and gives each git worktree its own branch subdomain.

Run portless with --no-tls so everything stays on HTTP. The Convex backend reaches the browser over a WebSocket on its own local port; an HTTPS frontend would block that as mixed content, plain HTTP does not.

Point the harness at the named URL with PORTLESS_SITE_URL. The dev/test wrappers then hand port control to portless, and the same URL flows into the Convex SITE_URL/trusted origin and Playwright's base URL:

PORTLESS_SITE_URL=http://myapp.localhost bun run dev
PORTLESS_SITE_URL=http://myapp.localhost bun run test:e2e

This stays optional: a plain clone needs nothing extra and never has to install portless or grant it the privileged ports it binds.

</details>

User Settings

Users can update their profile, change their password with live strength feedback, swap their email (triggers re-verification), manage passkeys, and review or revoke active sessions. Uploaded avatars and attachments are validated on the server and cleaned up automatically.

Type-Safe Environment Variables

varlock validates env vars against two schemas and generates TypeScript types from them. .env.schema covers SvelteKit (Vite), .env-convex.schema covers the Convex backend. If a required variable is missing or mistyped, you find out before the app starts.

VS Code Integration

Dev server, static checks, i18n sync, email build, and worktree creation are all available as VS Code tasks via Run Task (Cmd/Ctrl+Shift+P).