Staging Environment & Local Development
Staging Cloudflare Worker architecture, build order (build:web -> build:worker), Cloudflare Access Service Token smoke verification, Stripe sandbox, and QA tools.
Staging runs entirely on Cloudflare Workers (slloy-staging-api at https://staging.slloy.com), backed by Neon PostgreSQL 17 (slloy_staging via Hyperdrive slloy-staging-neon), Cloudflare R2 (slloy-staging-uploads), and Cloudflare Queues (slloy-staging-images / -dlq).
1. Dual-Target wrangler.jsonc & Build Pipeline
A single wrangler.jsonc defines both targets: the top-level configuration is staging (slloy-staging-api), and env.production is production (slloy-production-api). Because bindings (vars, hyperdrive, r2_buckets, queues) do not inherit across environments in Wrangler, every environment block declares its full set of bindings explicitly.
Mandatory Build Sequence (build:web -> build:worker)
npm run build:web:- Builds the pre-rendered static site,
/adminSPA, and share scripts intodist/. - Compresses the runtime content required for
/promptsSSR (articles, dictionaries, page metadata) intodist/_worker/content/. The Worker reads this JSON via theASSETSbinding at runtime rather than bundling megabytes of content into the Worker script (/_worker/*returns404to external requests).
- Builds the pre-rendered static site,
npm run build:worker(withCLOUDFLARE_ENV=stagingorproduction):@cloudflare/vite-plugincompiles the SSR Worker into.worker-dist/ssr/wrangler.jsonand points.wrangler/deploy/config.jsonto it.- At the end of
build:worker,tools/worker-assets.tsrewritesassets.directoryin the generated config back todist/while keeping.worker-dist/clientsonpm run check:wranglercan verify asset hash consistency.
npm run check:wrangler -- --expect-target staging:- Verifies that
dist/_worker/content/exists, article bodies are not bundled inside the JS script, uncompressed Worker size is within the7,168 KiBbudget (WORKER_BUDGET_KIB), andtargetEnvironmentmatches.
- Verifies that
- Deployment (
npx wrangler deploy):- Never run
wrangler deploy -c wrangler.jsoncdirectly against source (esbuild cannot resolve TanStack Start virtual modules without Vite). Deploy via the generated config (npx wrangler deployfor staging,npx wrangler deploy --env productionfor production).
- Never run
2. Staging Bindings & Secrets
| Binding / Resource | Staging Value | Notes |
|---|---|---|
ASSETS | dist/ (run_worker_first: true) | Worker controls routing order: moved articles -> trailing slash -> /prompts SSR -> public HTML -> static assets -> 404. |
BUCKET (R2) | slloy-staging-uploads | Served at /uploads/* with HTTP Range support (206). |
HYPERDRIVE | slloy-staging-neon (5c835a380e414013a32766e360976705) | Connects directly to Neon slloy_staging (aws-ap-southeast-1, PostgreSQL 17, --caching-disabled). |
IMAGE_QUEUE | slloy-staging-images (DLQ: slloy-staging-images-dlq) | Async image generation queue. |
triggers.crons | */5 * * * *, 0 * * * * | Matches server/src/scheduled.ts. |
Staging Secrets (Top-Level Worker — Omit --env)
npx wrangler secret put ADMIN_JWT_SECRET -c wrangler.jsonc
npx wrangler secret put BETTER_AUTH_SECRET -c wrangler.jsonc
npx wrangler secret put STAGING_ACCESS_TEAM_DOMAIN -c wrangler.jsonc
npx wrangler secret put STAGING_ACCESS_AUD -c wrangler.jsonc- GitHub
stagingEnvironment Secrets:STAGING_NEON_DATABASE_URL(direct Neon connection string; migration assertscurrent_database() === 'slloy_staging'),STAGING_ACCESS_CLIENT_ID,STAGING_ACCESS_CLIENT_SECRET,CLOUDFLARE_API_TOKEN,CLOUDFLARE_ACCOUNT_ID. - Stripe Sandbox on Staging: Keep
PAYMENTS_ENABLED=falseby default, or connect a dedicated staging Stripe test sandbox (sk_test_*/rk_test_*—live keys are rejected at startup whenAPP_ENV=staging). Never share the same Stripe test sandbox between staging and localstripe listen.
3. QA Testing Portal (https://staging.slloy.com/staging)
Mounted only when APP_ENV=staging (server/src/http/routes/staging.ts):
- One-Click Test Account Creation: Creates a pre-verified test user (
qa_<MMDD>_<rand>@staging.invalid) with1,000credits and issues an immediate login session (zero emails sent, no password required). - One-Click Credit Top-Up: Refills the current test user's credits (recorded in ledger as admin adjustment).
- Browser Account Switcher: Switches between previously created
@staging.invalidaccounts (refuses to log into any real user domain). - One-Click
/adminLogin: WhenSTAGING_ADMIN_USERNAMEis configured, issues an admin session for that staging staff account and logs the caller's Cloudflare Access email.
4. Local Development Commands
npm ci
npm run db:up # Starts/reuses shared local PostgreSQL 17 container (slloy-postgres-local)
npm run db:init # Applies Drizzle migrations & seeds
npm run build:web # Generates dist/ static assets for Worker
npm run dev:web # Public site + /admin HMR on 127.0.0.1:5173 (auto-increments on port conflict)
npm run dev:api # Workerd via Vite on 127.0.0.1:8787 (writes actual port to .docker-postgres/dev-api.json)Or run npm run dev to launch database, Worker backend, and frontend dev servers together. To test local workerd against a remote Neon branch via Hyperdrive local connection override:
npm run build:web
CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE='postgresql://...@<neon-direct-host>/slloy_staging?sslmode=require' npm run dev:apiProduction Deployment Handbook (Cloudflare Workers)
Complete production architecture, Neon + Hyperdrive setup, R2 media buckets, Cloudflare Queues, Worker secrets, GitHub environment isolation, and rollback runbook.
Feature Environments (Per-Branch Preview Workers)
Ephemeral per-branch Cloudflare Workers (<name>.zsg8482.workers.dev), PR /feature-env slash commands, shared staging DB/R2 architecture, and automated TTL cleanup.