ADR-004: CI & Deploy — Vercel

Status

Accepted

Context

We wanted every pull request to get a preview URL and a deterministic build pipeline that runs next build plus linting before anything ships. Shipping the docs site should feel just as smooth.

Options considered

  • Vercel — Native support for Next.js, preview deploys, cron configuration in one place.
  • GitHub Actions + custom runners — Flexible, but more YAML, more secrets management.
  • Netlify / Cloudflare Pages — Solid, yet fewer guardrails for App Router specifics.

Decision

Adopt Vercel for both CI and deployment. The default build command runs npm run build from web/, which already executes linting. Preview deployments become QA sandboxes. For the docs app (astro-book/), we can wire a second Vercel project that points at the same repo.

Consequences

Upside

  • Zero-config previews, instant feedback for designers.
  • Secret management, analytics, and cron scheduling under one roof.
  • Easy rollbacks (we even wrote a how-to).

Trade-offs

  • Vendor coupling; running on bare metal later would take a new pipeline.
  • Need to watch build logs for optional dependency warnings (e.g., Rollup prebuilds).
  • Build scripts: web/package.json
  • Docs deploy script idea: astro-book/package.json
  • Related ADR: ADR-005