AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

netlify-deploy

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.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--netlify-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 5

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/