sc-vercel

/sc-vercel — Vercel (online frontend)

Status: implemented (online path).

flowchart TD
    A["/sc-vercel"] --> B["find/create Vercel project<br/>(bound to GitHub repo)"]
    B --> C["set CONVEX_DEPLOY_KEY (encrypted)"]
    C --> D["set coupled build cmd<br/>npx convex deploy --cmd 'npm run build'"]
    D --> E["add custom domain / subdomain"]
    E --> F["read required DNS from Vercel<br/>(array-normalized + IPv4 guard)"]
    F --> G["Hostinger DNS<br/>CNAME (sub) / A (apex)"]
    G --> H["trigger deploy + poll readyState<br/>(15-min cap, blip-tolerant)"]
    H --> I["live URL ✅<br/>NEXT_PUBLIC_CONVEX_URL injected at build"]

When to use

• You want Vercel's edge network for the Next.js frontend, with the Convex backend on Convex Cloud (managed).
• You don't want to deal with a Dockerfile / Compose for the frontend.
• The online counterpart to the self-hosted Dokploy path. Pair with /sc-convex-cloud for the backend.

Scope (implemented)

scripts/deploy.js is a single 12-step orchestrator:

1. Build a team-aware Vercel client from VERCEL_TOKEN (+ optional VERCEL_TEAM_ID).
2. Resolve the GitHub repo: --git-owner/--git-repo, else read origin from the local git remote.
3. findOrCreateProject({ name, gitRepo, framework:'nextjs' }) — bind the repo on create.
4. Set env vars: CONVEX_DEPLOY_KEY (type:'encrypted', Production only — it's a prod key). Do not set NEXT_PUBLIC_CONVEX_URL (injected by the build).
5. Resolve the build command without overriding the repo: explicit --build-command → repo vercel.json → Bun/npm-aware Convex fallback. This lets repos such as Baton keep their own gated bun run build:auto contract.
6. Add the custom domain/subdomain (tolerate 409 already-assigned).
7. Read the exact required DNS from Vercel's domain config.
8. Configure Hostinger DNS (TXT ownership challenge first if unverified, then the A/CNAME pointing record), or print the records to add manually if no HOSTINGER_API_TOKEN.
9. Trigger the first deploy (git-linked projects auto-deploy on push; force the initial one).
10. Poll getDeployment every 4s until readyState ∈ {READY, ERROR, CANCELED}.
11. Soft-poll DNS propagation (misconfigured === false) up to ~60s — never hard-fail (cert/record can lag).
12. Print summary: project id, deployment URL, custom domain, DNS record applied, Convex Cloud URL.