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:

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:

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:

# 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

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

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

React (Vite)

# 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

# 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:

   [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:

   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:

   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

# 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:

[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:

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

5. Build Locally First

Test builds locally before deploying:

npm run build
# Check that build output exists

npx netlify deploy --dir=dist

6. Use Deploy Messages

Add context to deployments:

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:

npx netlify logout
npx netlify login

"No site linked"

Cause: Project not connected to a Netlify site.

Fix:

# 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:

   [build.processing.css]
     bundle = true
     minify = true
   

2. Use caching headers for static assets:

   [[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/