Netlify Deploy

# Netlify Deployment Skill

Deploy web projects to Netlify using the Netlify CLI with intelligent detection of project configuration and deployment context.

## Overview

This skill automates Netlify deployments by: - Verifying Netlify CLI authentication - Detecting project configuration and framework - Linking to existing sites or creating new ones - Deploying to production or preview environments

## Prerequisites

- **Netlify CLI**: Installed via npx (no global install required) - **Authentication**: Netlify account with active login session - **Project**: Valid web project in current directory - When sandboxing blocks the deployment network calls, rerun with `sandbox_permissions=require_escalated`. - The deployment might take a few minutes. Use appropriate timeout values.

## Authentication Pattern

The skill uses the **pre-authenticated Netlify CLI** approach:

1. Check authentication status with `npx netlify status` 2. If not authenticated, guide user through `npx netlify login` 3. Fail gracefully if authentication cannot be established

Authentication uses either: - **Browser-based OAuth** (primary): `netlify login` opens browser for authentication - **API Key** (alternative): Set `NETLIFY_AUTH_TOKEN` environment variable

## Workflow

### 1. Verify Netlify CLI Authentication

Check if the user is logged into Netlify:

```bash npx netlify status ```

**Expected output patterns**: - ✅ Authenticated: Shows logged-in user email and site link status - ❌ Not authenticated: "Not logged into any site" or authentication error

**If not authenticated**, guide the user:

```bash npx netlify login ```

This opens a browser window for OAuth authentication. Wait for user to complete login, then verify with `netlify status` again.

**Alternative: API Key authentication**

If browser authentication isn't available, users can set:

```bash export NETLIFY_AUTH_TOKEN=your_token_here ```

Tokens can be generated at: https://app.netlify.com/user/applications#personal-access-tokens

### 2. Detect Site Link Status

From `netlify status` output, determine: - **Linked**: Site already connected to Netlify (shows site name/URL) - **Not linked**: Need to link or create site

### 3. Link to Existing Site or Create New

**If already linked** → Skip to step 4

**If not linked**, attempt to link by Git remote:

```bash # Check if project is Git-based git remote show origin

# If Git-based, extract remote URL # Format: https://github.com/username/repo or git@github.com:username/repo.git

# Try to link by Git remote npx netlify link --git-remote-url <REMOTE_URL> ```

**If link fails** (site doesn't exist on Netlify):

```bash # Create new site interactively npx netlify init ```

This guides user through: 1. Choosing team/account 2. Setting site name 3. Configuring build settings 4. Creating netlify.toml if needed

### 4. Verify Dependencies

Before deploying, ensure project dependencies are installed:

```bash # For npm projects npm install

# For other package managers, detect and use appropriate command # yarn install, pnpm install, etc. ```

### 5. Deploy to Netlify

Choose deployment type based on context:

**Preview/Draft Deploy** (default for existing sites):

```bash npx netlify deploy ```

This creates a deploy preview with a unique URL for testing.

**Production Deploy** (for new sites or explicit production deployments):

```bash npx netlify deploy --prod ```

This deploys to the live production URL.

**Deployment process**: 1. CLI detects build settings (from netlify.toml or prompts user) 2. Builds the project locally 3. Uploads built assets to Netlify 4. Returns deployment URL

### 6. Report Results

After deployment, report to user: - **Deploy URL**: Unique URL for this deployment - **Site URL**: Production URL (if production deploy) - **Deploy logs**: Link to Netlify dashboard for logs - **Next steps**: Suggest `netlify open` to view site or dashboard

## Handling netlify.toml

If a `netlify.toml` file exists, the CLI uses it automatically. If not, the CLI will prompt for: - **Build command**: e.g., `npm run build`, `next build` - **Publish directory**: e.g., `dist`, `build`, `.next`

Common framework defaults: - **Next.js**: build command `npm run build`, publish `.next` - **React (Vite)**: build command `npm run build`, publish `dist` - **Static HTML**: no build command, publish current directory

The skill should detect framework from `package.json` if possible and suggest appropriate settings.

## Example Full Workflow

```bash # 1. Check authentication npx netlify status

# If not authenticated: npx netlify login

# 2. Link site (if needed) # Try Git-based linking first git remote show origin npx netlify link --git-remote-url https://github.com/user/repo

# If no site exists, create new one: npx netlify init

# 3. Install dependencies npm install

# 4. Deploy (preview for testing) npx netlify deploy

# 5. Deploy to production (when ready) npx netlify deploy --prod ```

## Error Handling

Common issues and solutio