Netlify Deploy

1---
2name: netlify-deploy
3description: Deploy web projects to Netlify using the Netlify CLI (`npx netlify`). Use when the user asks to deploy, host, publish, or link a site/repo on Netlify, including preview and production deploys.
4---
5 
6# Netlify Deployment Skill
7 
8Deploy web projects to Netlify using the Netlify CLI with intelligent detection of project configuration and deployment context.
9 
10## Overview
11 
12This skill automates Netlify deployments by:
13- Verifying Netlify CLI authentication
14- Detecting project configuration and framework
15- Linking to existing sites or creating new ones
16- Deploying to production or preview environments
17 
18## Prerequisites
19 
20- **Netlify CLI**: Installed via npx (no global install required)
21- **Authentication**: Netlify account with active login session
22- **Project**: Valid web project in current directory
23- When sandboxing blocks the deployment network calls, rerun with `sandbox_permissions=require_escalated`.
24- The deployment might take a few minutes. Use appropriate timeout values.
25 
26## Authentication Pattern
27 
28The skill uses the **pre-authenticated Netlify CLI** approach:
29 
301. Check authentication status with `npx netlify status`
312. If not authenticated, guide user through `npx netlify login`
323. Fail gracefully if authentication cannot be established
33 
34Authentication uses either:
35- **Browser-based OAuth** (primary): `netlify login` opens browser for authentication
36- **API Key** (alternative): Set `NETLIFY_AUTH_TOKEN` environment variable
37 
38## Workflow
39 
40### 1. Verify Netlify CLI Authentication
41 
42Check if the user is logged into Netlify:
43 
44```bash
45npx netlify status
46```
47 
48**Expected output patterns**:
49- ✅ Authenticated: Shows logged-in user email and site link status
50- ❌ Not authenticated: "Not logged into any site" or authentication error
51 
52**If not authenticated**, guide the user:
53 
54```bash
55npx netlify login
56```
57 
58This opens a browser window for OAuth authentication. Wait for user to complete login, then verify with `netlify status` again.
59 
60**Alternative: API Key authentication**
61 
62If browser authentication isn't available, users can set:
63 
64```bash
65export NETLIFY_AUTH_TOKEN=your_token_here
66```
67 
68Tokens can be generated at: https://app.netlify.com/user/applications#personal-access-tokens
69 
70### 2. Detect Site Link Status
71 
72From `netlify status` output, determine:
73- **Linked**: Site already connected to Netlify (shows site name/URL)
74- **Not linked**: Need to link or create site
75 
76### 3. Link to Existing Site or Create New
77 
78**If already linked** → Skip to step 4
79 
80**If not linked**, attempt to link by Git remote:
81 
82```bash
83# Check if project is Git-based
84git remote show origin
85 
86# If Git-based, extract remote URL
87# Format: https://github.com/username/repo or git@github.com:username/repo.git
88 
89# Try to link by Git remote
90npx netlify link --git-remote-url <REMOTE_URL>
91```
92 
93**If link fails** (site doesn't exist on Netlify):
94 
95```bash
96# Create new site interactively
97npx netlify init
98```
99 
100This guides user through:
1011. Choosing team/account
1022. Setting site name
1033. Configuring build settings
1044. Creating netlify.toml if needed
105 
106### 4. Verify Dependencies
107 
108Before deploying, ensure project dependencies are installed:
109 
110```bash
111# For npm projects
112npm install
113 
114# For other package managers, detect and use appropriate command
115# yarn install, pnpm install, etc.
116```
117 
118### 5. Deploy to Netlify
119 
120Choose deployment type based on context:
121 
122**Preview/Draft Deploy** (default for existing sites):
123 
124```bash
125npx netlify deploy
126```
127 
128This creates a deploy preview with a unique URL for testing.
129 
130**Production Deploy** (for new sites or explicit production deployments):
131 
132```bash
133npx netlify deploy --prod
134```
135 
136This deploys to the live production URL.
137 
138**Deployment process**:
1391. CLI detects build settings (from netlify.toml or prompts user)
1402. Builds the project locally
1413. Uploads built assets to Netlify
1424. Returns deployment URL
143 
144### 6. Report Results
145 
146After deployment, report to user:
147- **Deploy URL**: Unique URL for this deployment
148- **Site URL**: Production URL (if production deploy)
149- **Deploy logs**: Link to Netlify dashboard for logs
150- **Next steps**: Suggest `netlify open` to view site or dashboard
151 
152## Handling netlify.toml
153 
154If a `netlify.toml` file exists, the CLI uses it automatically. If not, the CLI will prompt for:
155- **Build command**: e.g., `npm run build`, `next build`
156- **Publish directory**: e.g., `dist`, `build`, `.next`
157 
158Common framework defaults:
159- **Next.js**: build command `npm run build`, publish `.next`
160- **React (Vite)**: build command `npm run build`, publish `dist`
161- **Static HTML**: no build command, publish current directory
162 
163The skill should detect framework from `package.json` if possible and suggest appropriate settings.
164 
165## Example Full Workflow
166 
167```bash
168# 1. Check authentication
169npx netlify status
170 
171# If not authenticated:
172npx netlify login
173 
174# 2. Link site (if needed)
175# Try Git-based linking first
176git remote show origin
177npx netlify link --git-remote-url https://github.com/user/repo
178 
179# If no site exists, create new one:
180npx netlify init
181 
182# 3. Install dependencies
183npm install
184 
185# 4. Deploy (preview for testing)
186npx netlify deploy
187 
188# 5. Deploy to production (when ready)
189npx netlify deploy --prod
190```
191 
192## Error Handling
193 
194Common issues and solutions:
195 
196**"Not logged in"**
197→ Run `npx netlify login`
198 
199**"No site linked"**
200→ Run `npx netlify link` or `npx netlify init`
201 
202**"Build failed"**
203→ Check build command and publish directory in netlify.toml or CLI prompts
204→ Verify dependencies are installed
205→ Review build logs for specific errors
206 
207**"Publish directory not found"**
208→ Verify build command ran successfully
209→ Check publish directory path is correct
210 
211## Troubleshooting
212 
213### Escalated Network Access
214 
215If deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use `sandbox_permissions=require_escalated`). The deploy requires escalated network access when sandbox networking blocks outbound requests.
216 
217Example guidance to the user:
218 
219```
220The deploy needs escalated network access to deploy to Netlify. I can rerun the command with escalated permissions—want me to proceed?
221```
222 
223## Environment Variables
224 
225For secrets and configuration:
226 
2271. Never commit secrets to Git
2282. Set in Netlify dashboard: Site Settings → Environment Variables
2293. Access in builds via `process.env.VARIABLE_NAME`
230 
231## Tips
232 
233- Use `netlify deploy` (no `--prod`) first to test before production
234- Run `netlify open` to view site in Netlify dashboard
235- Run `netlify logs` to view function logs (if using Netlify Functions)
236- Use `netlify dev` for local development with Netlify Functions
237 
238## Reference
239 
240- Netlify CLI Docs: https://docs.netlify.com/cli/get-started/
241- netlify.toml Reference: https://docs.netlify.com/configure-builds/file-based-configuration/
242 
243## Bundled References (Load As Needed)
244 
245- [CLI commands](references/cli-commands.md)
246- [Deployment patterns](references/deployment-patterns.md)
247- [netlify.toml guide](references/netlify-toml.md)
248