davila7--claude-code-templates/cli-tool/components/skills/development/netlify-deploy/references/deployment-patterns.md

# Netlify Deployment Patterns

Common deployment scenarios and best practices for the Netlify skill.

## Deployment Decision Tree

```
Is user authenticated?
├─ No → Run `netlify login`
└─ Yes → Is site linked?
    ├─ No → Is it a Git repo?
    │   ├─ Yes → Try `netlify link --git-remote-url`
    │   │   ├─ Success → Continue to deploy
    │   │   └─ Fail → Run `netlify init`
    │   └─ No → Run `netlify init`
    └─ Yes → Is this first deploy or existing site?
        ├─ First deploy/new site → `netlify deploy --prod`
        └─ Existing site → `netlify deploy` (preview)
```

## Scenario 1: First-Time Deployment (New Project)

**Context**: User has a project that has never been deployed to Netlify.

**Steps**:
1. Check authentication: `npx netlify status`
2. If not authenticated: `npx netlify login`
3. Initialize new site: `npx netlify init`
   - This guides user through setup
   - Creates netlify.toml if needed
4. Install dependencies: `npm install`
5. Deploy to production: `npx netlify deploy --prod`

**Example**:
```bash
npx netlify status
# Not linked to a site

npx netlify login
# Opens browser for authentication

npx netlify init
# Walks through site creation

npm install
npx netlify deploy --prod
```

## Scenario 2: Linking Existing Git Repository to Existing Site

**Context**: User has a site already on Netlify and wants to link their local repo.

**Steps**:
1. Check authentication: `npx netlify status`
2. Get Git remote: `git remote show origin`
3. Extract URL (e.g., `https://github.com/user/repo.git`)
4. Link by remote: `npx netlify link --git-remote-url <URL>`
5. If found, linked. If not, run `netlify init`

**Example**:
```bash
git remote show origin
# * remote origin
#   Fetch URL: https://github.com/user/my-app.git

npx netlify link --git-remote-url https://github.com/user/my-app.git
# Site linked successfully
```

## Scenario 3: Preview Deployment (Testing Changes)

**Context**: User wants to test changes before pushing to production.

**Steps**:
1. Ensure site is linked: `npx netlify status`
2. Make code changes
3. Deploy preview: `npx netlify deploy`
4. Review preview URL
5. If approved, deploy to prod: `npx netlify deploy --prod`

**Example**:
```bash
# Make changes to code

npx netlify deploy
# Draft deploy URL: https://507f1f77bcf86cd799439011-my-app.netlify.app

# Test the preview, then:
npx netlify deploy --prod
```

## Scenario 4: Framework-Specific Deployments

### Next.js

```bash
# Next.js typically uses .next as output
npx netlify deploy --prod

# netlify.toml should have:
# [build]
#   command = "npm run build"
#   publish = ".next"
```

### React (Vite)

```bash
# Vite outputs to dist by default
npm run build
npx netlify deploy --dir=dist --prod

# netlify.toml:
# [build]
#   command = "npm run build"
#   publish = "dist"
```

### Static HTML

```bash
# No build step needed
npx netlify deploy --dir=. --prod
```

## Scenario 5: Monorepo Deployment

**Context**: Project is in a subdirectory of a monorepo.

**Steps**:
1. Navigate to project subdirectory: `cd packages/frontend`
2. Or set base in netlify.toml:
   ```toml
   [build]
     base = "packages/frontend"
     command = "npm run build"
     publish = "dist"
   ```
3. Deploy normally: `npx netlify deploy --prod`

## Scenario 6: Environment Variables

**Context**: Project needs secrets or environment-specific config.

**Steps**:
1. Never commit secrets to Git
2. Set in Netlify dashboard or CLI:
   ```bash
   npx netlify env:set API_KEY "secret_value"
   npx netlify env:set NODE_ENV "production"
   ```
3. Access in code: `process.env.API_KEY`
4. Deploy: `npx netlify deploy --prod`

## Scenario 7: Custom Domain Setup

**Context**: User wants to use a custom domain.

**Steps**:
1. Deploy site first: `npx netlify deploy --prod`
2. Add domain via dashboard or CLI:
   ```bash
   npx netlify open:admin
   # Navigate to Domain settings
   ```
3. Update DNS records as instructed by Netlify
4. Wait for DNS propagation (can take up to 48 hours)

## Best Practices

### 1. Always Preview First

```bash
# Deploy preview
npx netlify deploy

# Test thoroughly
# Then deploy to production
npx netlify deploy --prod
```

### 2. Use netlify.toml for Consistency

Create a `netlify.toml` file in your repo root:

```toml
[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
```

This ensures consistent builds across all deployments.

### 3. Framework Detection

Let Netlify auto-detect when possible. Only specify build settings if:
- Netlify can't detect your framework
- You need custom build commands
- Your project has a non-standard structure

### 4. Dependency Installation

Always ensure dependencies are installed before deploying:

```bash
npm install  # or yarn install, pnpm install
npx netlify deploy
```

### 5. Build Locally First

Test builds locally before deploying:

```bash
npm run build
# Check that build output exists

npx netlify deploy --dir=dist
```

### 6. Use Deploy Messages

Add context to deployments:

```bash
npx netlify deploy --prod --message="Fix login bug"
```

## Error Recovery Patterns

### "Publish directory not found"

**Cause**: Build command didn't create expected output directory.

**Fix**:
1. Run build locally: `npm run build`
2. Check output directory name
3. Update netlify.toml or CLI prompts with correct path

### "Command failed with exit code 1"

**Cause**: Build command failed.

**Fix**:
1. Check build logs for specific error
2. Run build locally to reproduce: `npm run build`
3. Fix the build error
4. Deploy again

### "Not logged in"

**Cause**: Authentication token expired or missing.

**Fix**:
```bash
npx netlify logout
npx netlify login
```

### "No site linked"

**Cause**: Project not connected to a Netlify site.

**Fix**:
```bash
# Try linking to existing site
npx netlify link

# Or create new site
npx netlify init
```

## Performance Tips

1. **Enable processing** in netlify.toml for auto-optimization:
   ```toml
   [build.processing.css]
     bundle = true
     minify = true
   ```

2. **Use caching headers** for static assets:
   ```toml
   [[headers]]
     for = "/assets/*"
     [headers.values]
       Cache-Control = "public, max-age=31536000, immutable"
   ```

3. **Optimize images** before deploying or use Netlify Image CDN

4. **Use Netlify Functions** for serverless backend (avoid external API calls when possible)

## Resources

- Netlify CLI Documentation: https://docs.netlify.com/cli/get-started/
- Framework Integration Guides: https://docs.netlify.com/frameworks/
- Build Configuration: https://docs.netlify.com/configure-builds/