The Next.js portfolio runs on Vercel; the Party WebSocket backend runs on Cloudflare Workers with SQLite Durable Objects. The local Node companion is for development. Deploying the Next.js project does not start that companion.
Use Node.js 22, matching .nvmrc and package.json:
nvm use
npm ci
npm run check
npm audit
npx --no-install drizzle-kit check
npm run party:worker:check:staging
git diff --check
git status --shortcheck includes lint, application types, Markdown tests, server regressions, Party tests, Worker types/bundling and the Webpack production build. It does not start browsers or contact a live database. The WebSocket test binds an isolated local port. The server regression uses an in-memory Postgres instance with the Neon transport replaced.
Deploy a reviewed commit and record its SHA before publishing. Keep .env* secrets, .party-data, .wrangler, node_modules, build output, design proposals and local review notes out of commits. Preserve AGENTS.md and source licenses. Local drafts and review history belong in ignored drafts/.
npx --no-install wrangler login
npx --no-install wrangler whoamiConfirm the intended Cloudflare account and Workers subdomain. The staging ALLOWED_ORIGINS in workers/party/wrangler.jsonc is https://staging.sanjaibalajee.com. Connect that hostname to the intended Vercel staging deployment and ensure DNS/TLS work before testing. Allow other preview hosts explicitly when needed, including https:// and without a trailing slash. Do not allow every *.vercel.app site.
The staging Worker is named sanjai-party-staging. Its room and quota bindings belong to that Worker, keeping them separate from production. Environment bindings/variables are repeated explicitly because Wrangler does not inherit those fields. Preserve the top-level v1 migration and both exported classes (PartyRoom, PartyQuota) in every future release. Do not mix a new Durable Object lifecycle format into this rollout. See Cloudflare environments and migration guidance.
npm run party:worker:check:staging
npm run party:worker:deploy:stagingCopy the HTTPS Worker URL returned by deployment. Curated games work immediately without an AI key. If Group Lore is required, rotate the Groq key before enabling public AI, then enter the new key at the hidden prompt:
npx --no-install wrangler secret put GROQ_API_KEY --config workers/party/wrangler.jsonc --env stagingSecrets are scoped to each Worker environment; repeat the secret command separately for production when ready. Keep GROQ_API_KEY off Vercel and out of tracked files. AI limits are 5 requests/day in staging and 40/day in production, enforced by separate quota objects. Review provider limits and actual cost before changing those values. Cloudflare secret management.
Use the existing portfolio project, with repository root ./, framework Next.js, Node.js 22.x and automatic .next output. vercel.json supplies npm ci and npm run build; the build uses Webpack. Do not set an out/static-export output directory. Next.js on Vercel.
Add these variables in the project's Preview environment, using an isolated Neon branch/database and a separate preview OAuth App when testing private sign-in:
| Variable | Value / purpose |
|---|---|
DATABASE_URL |
Preview Neon connection string, with the existing guestbook/auth/Switch schema |
AUTH_SECRET |
Strong random secret; shared with anonymous blog likes |
AUTH_GITHUB_ID, AUTH_GITHUB_SECRET |
Preview GitHub OAuth App credentials |
ALLOWED_GITHUB_ID |
87613424, the owner account's immutable GitHub ID |
AUTH_TRUST_HOST |
true (the app also sets this explicitly) |
SWITCH_INGEST_TOKEN |
Shared with the private sync job; use preview credentials for preview testing |
PARTY_SERVER_URL |
https://<staging-worker-host> |
PARTY_WS_URL |
wss://<staging-worker-host> |
The two Party URLs are public connection information passed by the server to the browser. No NEXT_PUBLIC_ prefix is needed. Do not put GROQ_API_KEY, PARTY_PORT, PARTY_HOST, PARTY_ALLOWED_ORIGINS or PARTY_DATA_DIR on Vercel. Local room files are not production storage.
The Trigger.dev task remains a separate deployment. Its LeetCode cookies, INGEST_URL and INGEST_TOKEN belong in Trigger.dev. Set production INGEST_URL=https://www.sanjaibalajee.com/api/switch/ingest; retain the existing token so it matches Vercel's SWITCH_INGEST_TOKEN. Update the dashboard value even if local .env.trigger is already corrected. Use the canonical endpoint directly: cross-host redirects can strip the bearer authorization header. Preview uses its own deployed ingest URL and token. TRIGGER_PROJECT_REF is not a Vercel runtime requirement.
Environment changes apply to a new deployment, so redeploy after changing them. Use the Git-connected branch's preview deployment; keep a record of its commit and URL. Preview protection may require signing in before testing. Vercel environment variables.
Verify the selected database target in a trusted shell. Supply its DATABASE_URL through your secret manager or a hidden prompt; do not paste credentials into command history. An exported value takes precedence over .env.local in this script.
npm run db:likesRun this separately for preview and production if their table is absent. It is safe to rerun and checks the expected columns. Do not run npm run db:migrate against an existing portfolio database as part of this release: drizzle/0000_switch_rewrite.sql contains DROP statements. A genuinely new database needs a separately reviewed baseline, not a blind replay. Existing guestbook records must remain intact. The ingest fix changes transaction behavior without requiring a new schema.
First verify CORS without creating a room. Substitute the actual Worker and preview origins:
curl -i -X OPTIONS 'https://<staging-worker-host>/rooms' -H 'Origin: https://<preview-host>' -H 'Access-Control-Request-Method: POST'
curl -i -X OPTIONS 'https://<staging-worker-host>/rooms' -H 'Origin: https://untrusted.example' -H 'Access-Control-Request-Method: POST'Expect 204 with the exact allowed origin, and 403 for the untrusted origin. The Worker intentionally rejects requests with no Origin; a bare curl / is not a health check.
- With at least three connected browser seats, complete create/join → private role → answers/votes → reveal → rematch. Verify a second room cannot see the first room's data.
- Reopen a seat in another tab, then background/foreground the displaced tab. It must remain closed until explicit reload. Test a connection drop and a mobile sleep/wake; pending votes/answers must not score twice.
- Check host handover after its 60-second disconnect grace, deadlines while clients sleep, consent withdrawal, an unconsenting display, and one-phone play without the backend.
- Confirm homepage/blog HTML and Markdown,
/index.md,/llms.txt,/feed.xml,/robots.txt,/sitemap.xml, sharing images and unknown-route 404s. - Confirm likes persist with a second browser, private Switch sign-in is owner-only, and a sync retry preserves submissions. Make guestbook/likes test writes only in the preview database and remove them afterward.
- Before enabling public guestbook writes, configure a Vercel Firewall rule for
POST /api/guestbook, starting with a per-IP threshold such as 5/minute and a 429/block response. Verify the rule on the current plan. Origin checks, an 8 KiB input cap and shared validation are in code; they are not a distributed spam throttle. WAF rate limiting.
Use two independent physical devices, including mobile Safari if supported. Automated Chromium tests and local Wrangler tests do not certify hosted hibernation, real mobile networks or provider account configuration.
- Recheck the release SHA and staging evidence. Record the previous Vercel deployment and Worker version for rollback.
- Production
ALLOWED_ORIGINScontains onlyhttps://www.sanjaibalajee.comandhttps://sanjaibalajee.com. Localhost access belongs in ignored.dev.vars; a no-secret example is supplied beside the Worker. - Run
npm run party:worker:check, thennpm run party:worker:deploy. These commands explicitly target the top-level production environment (--env ""). Copy its returned URL. Add the optional rotated Groq key withnpx --no-install wrangler secret put GROQ_API_KEY --config workers/party/wrangler.jsonc --env ""only when ready for AI use. - Set Vercel Production variables using production credentials and
https://<production-worker-host>/wss://<production-worker-host>. Ensure the additive likes table exists, the guestbook Firewall rule is active, and OAuth callback ishttps://www.sanjaibalajee.com/api/auth/callback/github. - Review any existing
AUTH_URL/NEXTAUTH_URLoverride; remove stale.mevalues or set the intended canonical production URL. Use preview-specific callbacks when testing previews. In Trigger.dev, setINGEST_URL=https://www.sanjaibalajee.com/api/switch/ingestin Production and verify it can read the watermark with the matching token. Changing ignored.env.triggerdoes not update the hosted task's environment. - Deploy the reviewed SHA through the production branch configured in Vercel, or create a staged Production-target deployment using Vercel's documented flow before assigning production domains. Do not blindly promote a Preview deployment carrying preview database/Worker credentials; verify the target environment first. Deployment promotion.
- Repeat the CORS and gameplay smoke checks on the public URLs. Inspect Vercel errors, Worker exceptions, quota usage and reconnects. Stop if authorization, private-state exposure, duplicate scoring, database errors or missing content metadata appears.
- In Vercel Domains, attach the canonical www
.com,.comapex and both legacy.mehosts. Use the dashboard's exact DNS records, wait for TLS, then verify a deep path and query redirect with 308 to www.com. DNS/TLS must work before the app's redirects can run. Do not guess DNS records from older notes.
Keep API/negotiated Markdown/WebSocket traffic out of any Cloudflare “cache everything” rule if Cloudflare also manages your DNS or proxy. Do not enable caching of private or negotiated responses.
Roll the frontend back to its recorded prior Vercel deployment if the release fails. If only multiplayer is affected, clear both Party URLs and redeploy to leave one-phone games available. Restore a prior Worker version only when it is compatible with current stored rooms; do not delete Durable Object namespaces, remove migration history, or replay the destructive database migration. The additive likes table can remain. AI can be disabled independently by removing the Worker secret.
The repository has two independent workflows:
| Workflow | Validates on relevant pull requests | Deploys after relevant pushes to main |
|---|---|---|
| Cloudflare Party | Party lint, all Party tests, production and staging Worker dry runs | Production sanjai-party Worker |
| Trigger.dev sync | Sync lint, generated Next.js types, application types and isolated server regressions | Production tasks in the project from trigger.config.ts |
Source, shared code, dependencies, Node version and each workflow's own file are included in its path filters. Blog-only edits do not redeploy either service. Pull requests run validation without deployment credentials. Validation does not execute the scheduled LeetCode task or make live database writes.
Both workflows also offer Run workflow with a staging or production choice. The default is staging. Production requires the latest main commit; a feature branch cannot deploy production. Deployments for each service/environment run one at a time without cancelling an active deployment. Jobs use the existing GitHub Preview and Production environments and respect their protection rules.
In repository Actions secrets, add:
| Secret | Purpose |
|---|---|
CLOUDFLARE_ACCOUNT_ID |
The account containing the Party Workers |
CLOUDFLARE_API_TOKEN |
An API token scoped to that account, with the permissions needed to edit the Workers and their Durable Object bindings |
TRIGGER_ACCESS_TOKEN |
A production deployment key for the project in trigger.config.ts |
TRIGGER_STAGING_ACCESS_TOKEN |
A separate staging deployment key; needed only for manual Trigger.dev staging deployments |
Use Cloudflare's CI authentication instructions to scope the token. Prefer a Trigger.dev environment API key with Deploy only access when the plan supports restricted keys, following its GitHub Actions instructions. Each Trigger.dev key must match the selected environment. Keys can instead be stored in the matching GitHub environment with the same names; environment secrets take precedence over repository secrets.
The GitHub CLI can prompt for each secret without placing its value in command history:
gh secret set CLOUDFLARE_ACCOUNT_ID
gh secret set CLOUDFLARE_API_TOKEN
gh secret set TRIGGER_ACCESS_TOKEN
# Only if using Trigger.dev staging:
gh secret set TRIGGER_STAGING_ACCESS_TOKENFor Cloudflare staging, set the repository Actions variable PARTY_STAGING_ALLOWED_ORIGINS to https://staging.sanjaibalajee.com, matching the staging Worker config. Multiple exact origins may be comma-separated, without spaces or trailing slashes. The workflow checks this value and overrides the tracked staging allowlist only for that deployment. It rejects missing values, wildcards and the placeholder. Keep production origins in workers/party/wrangler.jsonc.
Configuration verified on 29 October 2026: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN and TRIGGER_ACCESS_TOKEN are saved as repository Actions secrets. The staging origin variable is configured for https://staging.sanjaibalajee.com. The Cloudflare token portfolio-github-actions has Workers Scripts Write and Account Settings Read in the selected account. The separate Trigger.dev key github-actions-production has full access to this project's production environment, explicitly approved because the current Free plan blocks restricted deployment-only keys. Both new credentials expire on 27 January 2027; rotate the credentials and update the matching GitHub secrets before that date. No token values belong in this guide or Git.
Trigger.dev staging is unavailable on the current Free plan, so TRIGGER_STAGING_ACCESS_TOKEN remains unset and manual Trigger staging deployments cannot run. Do not reuse the production key for staging. Cloudflare staging remains a separate available target. Creating and saving these credentials did not deploy either service. After merging the workflows to main, follow the hosted checks above; production runs require the production environment choice.
GROQ_API_KEYremains a Cloudflare Worker secret, set separately for staging and production. Ordinary code deployments do not rotate it.LEETCODE_SESSION,LEETCODE_CSRF_TOKEN,INGEST_URLandINGEST_TOKENremain in the selected Trigger.dev environment. They are not copied from local.env.triggeror stored in Actions. Production ingest must usehttps://www.sanjaibalajee.com/api/switch/ingestdirectly and match Vercel's ingest token.- Trigger.dev deploys the task definition, including its existing 02:00 India-time schedule; the workflow does not invoke a sync. The CLI version is read from the SDK installed by
npm ci, so it matches the lockfile instead of floating tolatest. PR validation checks types and server regressions; bundling and provider registration occur in the authenticated deployment job. - Vercel continues to deploy through its existing Git integration. Neither workflow changes frontend connection URLs, deploys the frontend, applies database migrations or orders Vercel's deployment relative to the Worker. Coordinate the first rollout as described above, and keep future Worker/client changes compatible while both deploy.
- If Cloudflare Builds or Trigger.dev's native GitHub integration is enabled for this repository, choose one deployment mechanism for each service to avoid duplicate deployments.