CGPT Netlify Deploy
Use this skill for Vite/React SPA deployment work. Treat deployment as a verifyable engineering workflow: inspect repo config, make minimal changes, run a local build when possible, then guide or execute Netlify steps depending on available tools and user approval.
Pre-Deploy Checklist
Confirm project type and branch.
- Inspect
package.json, build scripts, router setup, and current Git branch. - Do not switch branches unless the user asks.
- Inspect
Ensure
netlify.tomlexists at repo root.
[build]
command = "npm run build"
publish = "dist"
[build.environment]
NODE_VERSION = "20"
Add required build-time public variables under
[build.environment].- Vite browser variables must be present at build time and must use
VITE_prefixes. - Do not put
NODE_ENV = "production"innetlify.toml; it can prevent devDependencies such as Vite from installing. - Public Supabase anon keys may be committed if the project already treats them as public browser config.
- Vite browser variables must be present at build time and must use
Ensure SPA redirects exist.
- For React Router or client-side routing, create
public/_redirectswith exactly:
- For React Router or client-side routing, create
/* /index.html 200
- Build locally when feasible.
- Run the repo's build command.
- If dependencies are missing and network access is needed, ask for approval before installing.
Deployment Workflow
- Commit and push only when the user asks or deployment requires a Git-backed build.
- Create or select the Netlify site.
- Link the GitHub repository and production branch in Netlify.
- Verify the deploy log shows a real build, not just cached uploaded files.
- Open the deployed URL and test:
- root route
/ - at least one direct deep link
- browser console for build-time env errors
- refresh/deep-link behavior for SPAs
- root route
Failure Modes
| Symptom | Likely Cause | Fix |
|---|---|---|
vite: not found |
NODE_ENV=production caused devDependencies to be skipped |
Remove NODE_ENV; rebuild |
| Direct route returns 404 | Missing SPA redirect | Add public/_redirects |
| Blank app with env error | VITE_* vars missing during build |
Put vars in netlify.toml [build.environment]; trigger new build |
| Deploy says all files already uploaded | Netlify reused cached artifacts | Push a small committed change to force rebuild |
| Build command wrong | Netlify auto-detect mismatch | Set command and publish in netlify.toml |
Rules
- Preserve unrelated repo changes.
- Never expose server-side secrets in browser config.
- Do not claim deployment success until the deployed URL and deep links have been checked or the limitation is reported.
- Prefer project-specific values from
.env.example, README, or existing deployment notes; do not invent credentials.