Netlify Deploy

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:

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:

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:

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:

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

# If Git-based, extract remote URL
# Format: https://github.com/username/repo or [email protected]: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):

# Create new site interactively
npx netlify init

4. Verify Dependencies

Before deploying, ensure project dependencies are installed:

# For npm projects
npm install

5. Deploy to Netlify

Choose deployment type based on context:

Preview/Draft Deploy (default for existing sites):

npx netlify deploy

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

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

npx netlify deploy --prod

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

Error Handling

Common issues and solutions:

"Not logged in" → Run npx netlify login

"No site linked" → Run npx netlify link or npx netlify init

"Build failed" → Check build command and publish directory in netlify.toml or CLI prompts → Verify dependencies are installed → Review build logs for specific errors

"Publish directory not found" → Verify build command ran successfully → Check publish directory path is correct

References

• CLI commands
• Deployment patterns
• netlify.toml guide