1---
2name: deploy
3description: Verify and ship a web app to Vercel: typecheck, production build, env check, then deploy and report the URL. Use when the user says "deploy", "ship it", or "push to prod".
4---
5# public variant, safe to publish
6
7# Deploy Skill
8
9Ship a web app to Vercel. Use the generic flow below. If your app matches the
10special case (a monorepo app with a local-path dependency), use that section
11instead: the generic `vercel --prod` steps will fail for it.
12
13## Generic web app deploy
14
151. Run `npx tsc --noEmit` to check for type errors. Fix all errors before deploying.
162. Run `npm run build` to verify the production build succeeds.
173. Confirm `.env.local` exists and has every required var.
184. Run `vercel --prod` to deploy.
195. Report the deployment URL.
20
21## Special case: monorepo app with a local-path dependency
22
23If the app depends on a package via a local `file:` path (a shared component
24library that is not published to npm), Vercel's remote install cannot resolve
25it. Deploy prebuilt instead, from the app directory:
26
27```
28npx tsc --noEmit # 1. typecheck, must be clean
29npx vercel build --prod # 2. build locally (the file: dep resolves here)
30npx vercel deploy --prebuilt --prod --yes # 3. upload .vercel/output
31```
32
33The Vercel CLI must be authed as the account that owns the target
34scope/project, otherwise the deploy lands in the wrong place. Check with
35`npx vercel whoami` and set `--scope <YOUR_SCOPE>` if needed.
36
37### Rules (each prevents a specific failure)
38
39- **Deploy the prebuilt output, never a plain `vercel --prod` and never
40 `git push`.**
41 - If the project's git integration is disconnected or absent, a push to the
42 default branch produces no deployment at all. Pushing and assuming prod is
43 updated ships nothing. Verify a deployment was actually created.
44 - A plain `vercel --prod` triggers a remote install, which hits the
45 local-path failure below.
46
47- **Always build locally so the `file:` dependency resolves; never let Vercel
48 run a remote install.** A remote install on Vercel's build machine fails with
49 `ENOENT <path>` because the local path does not exist there.
50 `npx vercel build --prod` resolves it from your filesystem, and `--prebuilt`
51 uploads the finished output so Vercel never runs its own install.
52
53- **A production build must never write to the dev server's output directory.**
54 In `next.config.ts`, set `distDir` to a separate directory (for example
55 `.next-dev`) when `NODE_ENV === "development"`, so `next dev` and
56 `vercel build` write to physically separate directories.
57 - Failure prevented: `next build` wipes its output dir. When dev and prod
58 share `.next`, a prod build deletes the dev server's compiled CSS; the dev
59 server then 404s on `layout.css`, showing serif fonts and underlined
60 links, and it recurs after every deploy. Gitignore the dev dir and add it
61 to `tsconfig`'s `include` so Next's generated types are still picked up.
62 - If broken/serif styling appears in dev, check the CSS response code BEFORE
63 editing any CSS file (the CSS source is usually not the problem):
64 ```
65 curl -s localhost:3000/_next/static/css/app/layout.css -o /dev/null -w '%{http_code}'
66 ```
67 A non-200 confirms the build-clobber issue, not a CSS bug.
68
69## Verification
70
71Treat these as stop conditions. Every one must pass before calling a deploy done.
72
731. **Typecheck clean.** `npx tsc --noEmit` exits `0` and prints no errors.
74
752. **Local build succeeds.** `npx vercel build --prod` exits `0` and produces a
76 `.vercel/output` directory. Confirm: `test -d .vercel/output && echo OK`
77 prints `OK`.
78
793. **Deploy uploaded prebuilt.** `npx vercel deploy --prebuilt --prod --yes`
80 exits `0` and prints a production URL. A healthy prebuilt deploy completes
81 in roughly 10 seconds. If it instead runs a full remote build (much longer,
82 or fails with an `ENOENT` on the local-path dep), the prebuilt path was not
83 used. Stop and fix; do not retry blindly.
84
854. **Prod domain serves the new build.** Your production domain returns HTTP
86 `200`:
87 ```
88 curl -s -o /dev/null -w '%{http_code}' https://<YOUR_DOMAIN>
89 ```
90 prints `200`.
91
925. **No stale auto-deploy assumption.** Confirm the deployment you just
93 created is the current prod alias (`npx vercel ls` / `npx vercel inspect`
94 shows your new deployment aliased to the domain), not an older auto-deploy.
95
966. **Dev CSS intact (only if a `next dev` server is running).** The
97 `layout.css` curl above prints `200`. A non-200 means a build clobbered the
98 dev output; verify the split `distDir` is still in place.
99
meirlabs