netlify-deploy

name	netlify-deploy
description	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.

Netlify Deployment

Deploy web projects to Netlify using the CLI with automatic project detection.

Prerequisites

• Netlify CLI: via npx (no global install required)
• Authentication: active Netlify login session
• Project: valid web project in current directory

Workflow

1. Verify Authentication

npx netlify status

If not authenticated:

npx netlify login          # browser-based OAuth (primary)
# OR
export NETLIFY_AUTH_TOKEN=your_token_here  # API key alternative
# Tokens: https://app.netlify.com/user/applications#personal-access-tokens

2. Link Site

From netlify status, check if a site is already linked.

If not linked:

# Try Git-based linking first
git remote show origin
npx netlify link --git-remote-url <REMOTE_URL>

# If no site exists on Netlify:
npx netlify init

# Or create a new site directly (without linking)
npx netlify create --name my-site-name

netlify init guides through team selection, site naming, build settings, and netlify.toml creation.

3. Install Dependencies

npm install  # or yarn/pnpm as appropriate

4. Deploy

# Preview deploy (unique URL for testing)
npx netlify deploy

# Production deploy
npx netlify deploy --prod

# Stream deploy and function logs
npx netlify logs             # All logs
npx netlify logs:function     # Function logs only

5. Report Results

After deployment, report:

• Deploy URL (preview) or Site URL (production)
• Link to deploy logs in Netlify dashboard
• Suggest netlify open to view site

netlify.toml

If present, the CLI uses it automatically. If absent, the CLI prompts for:

• Build command: e.g., npm run build, next build
• Publish directory: e.g., dist, build, .next

Common framework defaults:

Framework	Build Command	Publish Dir
Next.js	npm run build	.next
React (Vite)	npm run build	dist
Static HTML	(none)	.

Detect framework from package.json and suggest appropriate settings.

Error Handling

Error	Solution
"Not logged in"	npx netlify login
"No site linked"	npx netlify link or npx netlify init
"Build failed"	Check build command, publish dir, dependencies; review build logs
"Publish directory not found"	Verify build ran successfully and path is correct

Environment Variables

Set secrets in Netlify dashboard (Site Settings → Environment Variables), not in Git.

Reference

• Netlify CLI Docs
• netlify.toml Reference
• CLI commands
• Deployment patterns
• netlify.toml guide

Netlify Database

Netlify offers a managed serverless PostgreSQL database (built on Neon).

# Create a database for the linked site
npx netlify db:init

# Open database shell
npx netlify db:shell

# Connection string available as environment variable
# DATABASE_URL is auto-injected into Netlify Functions at runtime

• Serverless Postgres (Neon-backed), auto-scales to zero
• Connection string auto-provisioned as DATABASE_URL
• Use with Prisma, Drizzle, or raw pg client in Netlify Functions
• Docs: https://docs.netlify.com/database/overview/

Build Plugin Compatibility

Node 18 and Node 20 are no longer supported for Netlify Build Plugins (as of 2026). Build Plugins must target Node 22+. Update your plugin's engines field in package.json accordingly.