Skip to content

Melvynx/saveit.now / .agents/skills/ns-web-deploy

ns-web-deploy

Verified

Deploy the NowStack Mobile web app to production on Vercel with the Convex backend shipped alongside it. Use when the user says "deploy my app", "deploy the web app", "ship to production", "go live", or needs CONVEX_DEPLOY_KEY / the Vercel build wired so the backend never drifts behind the frontend.

Web Deploy - NowStack Mobile

Deploy web-app/ (TanStack Start) to Vercel so that Convex and the frontend ship together on every commit. The Vercel build runs convex deploy first, then builds the site — without this, the frontend ships against a stale backend. Run these steps IN ORDER; never skip the deploy-key step (Step 2 is the one teams forget).

npm run check-setup    # "web-app/vercel.json" AND "web-app nitro plugin" checks MUST pass
  1. web-app/vercel.json runs npm run build:vercel → cd .. && npx convex deploy --cmd 'cd web-app && npm run build' --cmd-url-env-var-name VITE_CONVEX_URL.
  2. The nitro host preset is wired so SSR routes serve on Vercel.

If either is missing (older project), restore them:

// web-app/vercel.json
{ "installCommand": "npm install && npm --prefix .. install", "buildCommand": "npm run build:vercel" }
// web-app/package.json scripts:
// "build:vercel": "cd .. && npx convex deploy --cmd 'cd web-app && npm run build' --cmd-url-env-var-name VITE_CONVEX_URL"
// web-app/vite.config.ts — add the nitro plugin (after tanstackStart(), before react()/tailwind())
import { nitro } from "nitro/vite";
// plugins: [ tanstackStart({...}), nitro(), viteReact(), tailwindcss() ]
// and add "nitro": "^3.0.260610-beta" to web-app dependencies, then `cd web-app && npm install`.

Sanity-check locally that the build emits the Vercel output (Node 22):

cd web-app && VERCEL=1 npm run build   # must end with "Generated .vercel/output/nitro.json"; trash .vercel/output after

setup:vercel (scripts/setup-vercel-convex.mjs):

  • Sets the Vercel project Root Directory = web-app automatically via the Vercel API (using the token the CLI already stored), so Vercel reads web-app/vercel.json. If it can't (no token), it prints the one manual step.
  • Mints a Convex production deploy key (convex deployment token create --prod) and sets CONVEX_DEPLOY_KEY (Production) + VITE_CONVEX_SITE_URL (auth) + VITE_EMAIL_CONTACT on Vercel.

Idempotent — safe to re-run; npm run setup:vercel -- --force rotates the key.

Link at the repo root (not web-app/) so a CLI deploy uploads the whole monorepo. Root Directory = web-app then makes Vercel build inside web-app/, where .. reaches the root convex/ folder.

Prefer the dashboard? Convex → Settings → Deploy keys → "Generate production deploy key", add it to Vercel as CONVEX_DEPLOY_KEY (Production), and set Root Directory = web-app under Settings → Build & Deployment.

git push origin main

CLI alternative — from the REPO ROOT with --archive=tgz:

vercel --prod --archive=tgz     # repo root, NOT web-app/ (see <critical>)

Confirm in the build log that Convex deployed and Nitro produced the Vercel output:

> cd .. && npx convex deploy --cmd 'cd web-app && npm run build' --cmd-url-env-var-name VITE_CONVEX_URL
- Running 'cd web-app && npm run build' with environment variables "VITE_CONVEX_URL" and "CONVEX_SITE_URL" set...
✓ built in ...
ℹ Generated .vercel/output/nitro.json     # ← the Nitro→Vercel preset ran

Then check the deployment is Ready and hit the routes (a SPA-404 regression only shows here, not in the build):

for p in / /privacy /cgv /support /app /admin; do
  echo "$p -> $(curl -s -o /dev/null -w '%{http_code}' https://<your-domain>$p)"
done
# every public route must be 200 (not 404). Sign in and confirm /app and /admin.

<failure_modes>

  • Site deployed but every route 404s (NOT_FOUND) → the nitro plugin is missing, so Vercel served a SPA. Wire nitro() (Step 1) and redeploy. The build log will NOT show "Generated .vercel/output" when it's missing.
  • Error: Invalid request: 'files' should NOT have more than 15000 items → you deployed the monorepo inline from the repo root. Add --archive=tgz, or just push to main.
  • Command "npm install && npm --prefix .. install" exited with 254 → you ran vercel --prod from web-app/, so only web-app/ uploaded and .. is empty. Deploy from the repo root (with --archive=tgz) or push to main.
  • Build error: "no Convex deployment configuration found / CONVEX_DEPLOY_KEY" → run Step 2 (npm run setup:vercel). The classic "web deployed but Convex never updated" bug.
  • Vercel ignores the build command → Root Directory is not web-app, so web-app/vercel.json is not read. Re-run npm run setup:vercel (it sets it) or fix it in project settings.
  • Frontend can't reach the backend in prod → VITE_CONVEX_URL was hardcoded to a dev URL, or the deploy ran without the key. Re-run Step 2 and redeploy.
  • convex deploy can't find functions → the build did not cd ..; the convex/ folder lives at the repo root, not in web-app/. </failure_modes>

<success_metrics>

  • npm run check-setup "web-app/vercel.json" AND "web-app nitro plugin" checks pass.
  • CONVEX_DEPLOY_KEY (Production) + VITE_CONVEX_SITE_URL set on Vercel; Root Directory = web-app.
  • A production build log shows convex deploy running, then the frontend build, then Generated .vercel/output/nitro.json, and the deployment is Ready.
  • Every public route (/, /privacy, /cgv, /support) returns 200 — not 404.
  • No secret committed or printed. </success_metrics>
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall