Copy page

Configuration

Deploy on Vercel

What recit build writes is static: an index.html, its assets/, nothing to run on a server. Any static host serves it; this page walks through Vercel, from a Git repository or from your machine.

What gets deployed

A site on the Récit site framework detects Vercel by itself: when the VERCEL environment variable is set (Vercel sets it, and so does vercel build), the build writes .vercel/output next to dist/, with the prerendered pages, the redirects of recit.config.ts, clean URLs (/guide rather than /guide.html, with a 308 from the old form) and the Markdown version of each page for clients that ask for it. Nothing to configure.

vercel.json

One file at the root of the project tells Vercel how to install and build. For a deck:

JSON
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "installCommand": "pnpm install",
  "buildCommand": "pnpm exec recit build talk.md -o dist",
  "outputDirectory": "dist"
}

For a site on the Récit site framework, leave outputDirectory out (null): the build hands Vercel its own .vercel/output.

JSON
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "installCommand": "pnpm install",
  "buildCommand": "pnpm run build",
  "outputDirectory": null
}

framework: null stops Vercel from guessing a framework and overriding these commands.

From Git

1. Push the project to GitHub, GitLab or Bitbucket.
2. On vercel.com/new, import the repository. In a monorepo, set Root Directory to the folder of the deck or site (talks/intro, sites/docs); pnpm install run from there installs the whole workspace.
3. Leave Framework Preset on "Other": vercel.json gives the commands.
4. Deploy. Every push to the production branch updates the site; every other branch or pull request gets a preview URL.

In a monorepo with several sites, add an ignoreCommand to each vercel.json so that a push rebuilds only the sites it touched, for example "ignoreCommand": "npx nx-ignore <project>" with Nx.

From your machine

The Vercel CLI builds on your machine and uploads the result. Run it from the folder of the deck or site:

Bash
pnpm dlx vercel login                       # once
pnpm dlx vercel link                        # once: picks or creates the Vercel project
pnpm dlx vercel pull --yes                  # the project's settings and environment variables
pnpm dlx vercel build                       # runs vercel.json's build, writes .vercel/output
pnpm dlx vercel deploy --prebuilt           # uploads it: a preview URL

For production, pull its environment and add --prod to the last two:

Bash
pnpm dlx vercel pull --yes --environment=production
pnpm dlx vercel build --prod
pnpm dlx vercel deploy --prebuilt --prod

--prebuilt uploads what you built, so the deployment is exactly what you checked locally. A plain vercel deploy --prod uploads the sources and lets Vercel build them instead.

In a monorepo with one Vercel project per site, link the repository once from its root with vercel link --repo: the CLI then picks the right project from the folder you run it in.

Add .vercel to .gitignore: it holds the link and the build output, never the sources.

Domains

In the project's Settings → Domains, add the domain, then at your registrar point a subdomain to Vercel with a CNAME to cname.vercel-dns.com (an apex domain takes the A record Vercel shows). Vercel issues the certificate. Another name that should land on the same site (www, an old domain) is added as a redirect to the main one.

Récit's own sites

The sites of the Récit repository (recit.dev, docs.recit.dev…) deploy this way, one Vercel project per site, with commands that wrap the Vercel CLI. From the repository root:

Bash
pnpm vercel:login                 # once per machine
export VERCEL_SCOPE=recit         # the team
pnpm vercel:project --domain      # once: create the projects, connect Git, add the domains
pnpm vercel:domains               # check the DNS of every domain
pnpm vercel:deploy docs           # a preview of docs.recit.dev
pnpm vercel:deploy:prod docs www  # production

vercel:project can be replayed: it creates a missing project and updates an existing one (Root Directory, Node version, link, Git connection). Without a site name, every command acts on every site that has a vercel.json; --dry-run prints the calls without running them. A production deployment refuses uncommitted changes unless given --allow-dirty. .github/VERCEL.md in the repository lists the whole procedure, down to the DNS records.