Netlify Integration

When to Use This Skill

Use this skill when you need to:

Deployment & Configuration:

Deploy a Next.js application to Netlify
Configure netlify.toml for build settings, functions, redirects, or headers
Set up environment variables in Netlify Dashboard or CLI
Configure continuous deployment from Git (GitHub, GitLab, Bitbucket)

Functions Development:

Create Netlify serverless functions
Handle webhooks (Twilio, Telnyx, Stripe, etc.)
Debug function timeout issues (10s limit on free tier, 26s on Pro)
Implement background processing for long-running tasks

Troubleshooting:

Fix webhook timeout errors (especially for SMS/telephony apps)
Debug "Function not found" (404) errors
Resolve environment variable issues
Fix build failures or deployment errors

SMS/Telephony Projects:

Working on projects like Twilio-Aldea that handle SMS webhooks
Implementing immediate webhook acknowledgment + background processing
Validating webhook signatures (Twilio, Telnyx)

Quick Reference

Basic Netlify Function Handler

import type { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";

export const handler: Handler = async ( event: HandlerEvent, context: HandlerContext ) => { try { const body = JSON.parse(event.body || "{}");

// Process request
console.log("Request received:", body);

return {
  statusCode: 200,
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ success: true }),
};

} catch (error) { console.error("Error:", error); return { statusCode: 500, body: JSON.stringify({ error: "Internal server error" }), }; } };

Webhook with Immediate Response (Critical Pattern)

Solves the 60% message loss problem - return 200 immediately, process async:

export const handler: Handler = async (event, context) => { // Validate webhook signature const isValid = validateWebhook(event); if (!isValid) { return { statusCode: 401, body: "Unauthorized" }; }

// IMMEDIATE: Return 200 OK (< 200ms) const response = { statusCode: 200, body: JSON.stringify({ received: true }), };

// BACKGROUND: Process async (don't await) processWebhookAsync(event.body).catch(console.error);

return response; };

Essential netlify.toml for Next.js

[build] command = "npm run build" publish = ".next"

[build.environment] NODE_VERSION = "18" NEXT_TELEMETRY_DISABLED = "1"

[[plugins]] package = "@netlify/plugin-nextjs"

[functions] directory = ".netlify/functions" node_bundler = "esbuild"

API rewrites

[[redirects]] from = "/api/*" to = "/.netlify/functions/:splat" status = 200 force = true

Security headers

[[headers]] for = "/*" [headers.values] X-Frame-Options = "DENY" X-Content-Type-Options = "nosniff" Referrer-Policy = "strict-origin-when-cross-origin"

Environment Variables Setup (CLI)

Prerequisites - Link Project First:

Option 1: Interactive linking

netlify link

Option 2: Manual linking (create .netlify/state.json)

mkdir -p .netlify echo '{"siteId":"YOUR-SITE-ID-HERE"}' > .netlify/state.json

Find your site ID

netlify sites:list # Shows all sites with their IDs

Verify link worked

netlify status

Managing Environment Variables:

Set single variable (use --force to skip confirmation)

netlify env:set VARIABLE_NAME value netlify env:set VARIABLE_NAME "value with spaces" --force

Set for specific context (production, deploy-preview, branch-deploy, dev)

netlify env:set VARIABLE_NAME value --context production

Import from .env file

netlify env:import .env.production

List all variables

netlify env:list

Get specific variable value

netlify env:get VARIABLE_NAME

Delete variable

netlify env:unset VARIABLE_NAME

Clone variables from another site

netlify env:clone --from OTHER_SITE_ID

Bulk Add Example (from shell):

Add multiple env vars in sequence

netlify env:set API_KEY "sk-xxx" --force netlify env:set ENABLE_FEATURE "true" --force netlify env:set NEXT_PUBLIC_APP_URL "https://myapp.netlify.app" --force

Note: After adding/changing env vars, you may need to trigger a redeploy for changes to take effect in production.

Function Timeout Configuration

[functions] directory = ".netlify/functions" timeout = 10 # Default for all functions

Increase timeout for specific function

[[functions."webhook"]] timeout = 26 # Max for Pro tier (10s for free)

Raw Body Parsing for Signature Validation

Critical for Twilio/Telnyx webhook signature validation:

export const config = { api: { bodyParser: false, // Disable Next.js body parsing }, };

async function readRawBody(req: NextApiRequest): Promise<string> { return new Promise<string>((resolve, reject) => { let data = ''; req.setEncoding('utf8'); req.on('data', (chunk) => { data += chunk; }); req.on('end', () => resolve(data)); req.on('error', reject); }); }

export default async function handler(req: NextApiRequest, res: NextApiResponse) { const rawBody = await readRawBody(req);

// Validate signature with raw body const isValid = validateSignature(rawBody, req.headers['x-twilio-signature']); if (!isValid) { return res.status(401).json({ error: 'Invalid signature' }); }

// Process webhook... }

Database Error Logging Pattern

export const handler: Handler = async (event) => { try { await processMessage(data); return { statusCode: 200, body: 'Success' }; } catch (error: unknown) { const err = error instanceof Error ? error : new Error(String(error)); console.error('[Function] Error:', err);

// Log to database for visibility
await supabase.from('processing_errors').insert({
  error_message: err.message,
  error_stack: err.stack,
  created_at: new Date().toISOString(),
});

return { statusCode: 500, body: `Error: ${err.message}` };

} };

Connection Pooling Pattern

// Reuse connections across function invocations let supabaseClient: any = null;

function getSupabaseClient() { if (!supabaseClient) { supabaseClient = createClient( process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY! ); } return supabaseClient; }

export const handler: Handler = async (event, context) => { const supabase = getSupabaseClient(); // Use cached client - reduces cold start time };

Dynamic Base URL Detection

// Works in production, preview deploys, and localhost const baseUrl = getBaseUrl(req); const backgroundUrl = ${baseUrl}/.netlify/functions/background;

Input Validation with Zod

import { z } from "zod";

const WebhookSchema = z.object({ from: z.string().min(10).max(15), to: z.string().min(10).max(15), body: z.string().min(1).max(1600), messageId: z.string().uuid(), });

export const handler: Handler = async (event, context) => { try { const data = JSON.parse(event.body || "{}"); const validated = WebhookSchema.parse(data);

await processMessage(validated);
return { statusCode: 200, body: JSON.stringify({ success: true }) };

} catch (error) { if (error instanceof z.ZodError) { return { statusCode: 400, body: JSON.stringify({ error: "Validation failed", details: error.errors }), }; } throw error; } };

Key Concepts

Netlify Functions

Serverless functions that run on AWS Lambda
Located in .netlify/functions/ directory
Support Node.js, TypeScript, Go
Timeout limits: 10s (free tier), 26s (Pro tier)
Background functions: Name with -background.ts suffix for 15-minute timeout

netlify.toml

File-based configuration for Netlify deployments
Place in repository root
Controls build settings, functions, redirects, headers
Supports context-specific configs (production, deploy-preview, branch-deploy)

Environment Variables

Server-side: Access via process.env.VARIABLE_NAME (any name)
Client-side: Must prefix with NEXT_PUBLIC_ to expose to browser
Set in Netlify Dashboard (Site Settings → Environment Variables) or via CLI
Never commit .env files to Git

Webhook Timeout Problem

SMS providers (Twilio/Telnyx) require response within 10 seconds
AI processing takes 15-25 seconds
Solution: Return 200 immediately, process async in background function
Result: 0% timeout rate (from 60% failure)

Background Functions

Automatically detected by filename: function-name-background.ts
15-minute timeout (vs 10-26s for regular functions)
Perfect for long-running AI processing, data processing, etc.
No additional configuration needed

Next.js + Netlify Integration

Requires @netlify/plugin-nextjs plugin
Handles ISR, SSR, and static page generation
API routes automatically converted to serverless functions
Custom functions go in .netlify/functions/ (separate from pages/api/ )

Reference Files

Core Configuration

references/netlify_config.md
Complete netlify.toml reference with all configuration options (build, functions, redirects, headers, contexts)
references/environment_variables.md
Environment variable management, scopes, client vs server, bulk import/export

Functions Development

references/functions_best_practices.md
Patterns for functions: async processing, error handling, security, database operations, monitoring
references/production-patterns.md
8 real-world patterns from Twilio-Aldea production (webhook timeouts, background processing, error logging)

Troubleshooting

references/debugging.md
Comprehensive debugging guide for build failures, function errors, webhook issues, database problems

Official Netlify Documentation

references/official-docs/functions.md
Complete Netlify Functions guide with handler types, event structure, deployment
references/official-docs/environment-variables.md
Environment variable configuration, scopes, runtime access
references/official-docs/netlify-toml.md
File-based configuration reference
references/official-docs/nextjs.md
Next.js framework integration, ISR, SSR, optimization

Code Examples

assets/examples/webhook-function.ts
Webhook handler with immediate response pattern
assets/examples/background-function.ts
Background function for long-running processing
assets/examples/netlify.toml
Complete configuration example with comments
assets/examples/api-route.ts
Next.js API route with raw body parsing and signature validation

Project-Specific

references/twilio_aldea_specific.md
Patterns specific to Twilio-Aldea SMS platform (webhook handling, session management, unified provider interface)

GitHub Repository (NEW)

references/github/README.md

Official Netlify CLI README from GitHub (netlify/cli, 1,752 stars)

references/github/issues.md

12 GitHub issues showing common problems and solutions:

Build failures and deployment errors
Environment variable issues
Function timeout problems
Redirects and routing configuration
Local development setup

references/github/CHANGELOG.md

Complete version history with breaking changes and new features

references/github/releases.md

1,203 GitHub releases with detailed CLI changelog

references/github/file_structure.md

Repository structure (871 files) showing CLI source code organization

Working with This Skill

For Beginners

Start here if you're new to Netlify:

Deploy your first app:

Review the "Initial Deployment (Git Integration)" section below
Follow the step-by-step workflow
Use Quick Reference #3 as your starting netlify.toml template

Understand the basics:

Read references/official-docs/functions.md for Netlify Functions basics
Review the simple examples in Quick Reference (#1, #4)
Study references/official-docs/environment-variables.md for environment setup

Create your first function:

Copy the Basic Function Handler example (#1)
Place in .netlify/functions/hello.ts
Deploy and test at https://yoursite.netlify.app/.netlify/functions/hello

For Intermediate Users

Already familiar with Netlify basics:

Implement production patterns:

Study references/production-patterns.md for real-world examples
Implement Pattern 1 (immediate response + background processing) if handling webhooks
Review Pattern 5 (error logging to database) for better monitoring

Optimize your setup:

Add connection pooling (#8) to reduce cold starts
Implement proper error handling with database logging (#7)
Add input validation with Zod (#10)

Handle complex scenarios:

Learn raw body parsing (#6) for webhook signature validation
Configure context-specific builds in netlify.toml
Set up proxy patterns for API calls (Pattern 4 in production-patterns.md)

For Advanced Users

Building production-grade serverless apps:

Master webhook handling:

Deep dive into references/production-patterns.md Pattern 1 (webhook timeout solution)
Implement signature validation for Twilio/Telnyx webhooks
Design multi-function architectures (API routes + background functions)

Performance optimization:

Study cold start reduction techniques in references/functions_best_practices.md
Implement lazy loading for heavy dependencies
Configure function memory and timeout appropriately

Advanced debugging:

Use structured logging patterns for better observability
Implement performance metrics tracking
Set up comprehensive error logging with database persistence

Multi-environment setup:

Configure context-specific environments (production, staging, development)
Manage environment variables across contexts
Implement feature flags and A/B testing patterns

Common Workflows

Deploying a Next.js App to Netlify

Prepare repository:

Add netlify.toml (use Quick Reference #3 as template)

Add .env.example with all required variables

git add netlify.toml .env.example git commit -m "Add Netlify configuration" git push origin main

Connect to Netlify:

Visit Netlify Dashboard → "Add new site" → "Import an existing project"
Select Git provider and repository
Build settings auto-detected via netlify.toml

Set environment variables:

netlify env:set VARIABLE_NAME value

Or use Netlify Dashboard: Site Settings → Environment Variables

Deploy:

Automatic on git push, or manual: netlify deploy --prod

Fixing Webhook Timeout Issues

Symptom: 60% message loss, 504 Gateway Timeout errors

Solution:

Identify if processing takes > 10 seconds
Implement immediate response pattern (Quick Reference #2)
Create background function with -background.ts suffix
Move long-running processing to background function
Test with: netlify dev locally

See: references/production-patterns.md Pattern 1 for complete implementation

Debugging Function Errors

Check function logs:

netlify functions:log function-name --stream

Add structured logging:

console.log(JSON.stringify({ timestamp: new Date().toISOString(), level: "error", message: "Error details", context: { requestId: context.requestId } }));

Test locally:

netlify dev

Test at http://localhost:8888/.netlify/functions/function-name

Review common issues:

See references/debugging.md for comprehensive troubleshooting guide

Version History

v2.0 (2025-11-01) - Enhanced with official Netlify documentation, production patterns from Twilio-Aldea, TypeScript examples, webhook timeout solutions, and comprehensive Next.js integration guide. Added 10 practical Quick Reference examples extracted from real production code.
v1.0 - Initial skill creation with deployment workflows, configuration, functions development, debugging

Additional Resources

Official Documentation:

Netlify Functions
Next.js on Netlify
Environment Variables

Netlify CLI:

Install: npm install -g netlify-cli
Login: netlify login
Docs: netlify help

Helper Scripts:

scripts/check_deployment.sh
Check deployment status and health
scripts/setup_env_vars.sh
Bulk configure environment variables
scripts/test_function_locally.sh
Test Netlify functions locally

netlify-integration

Safety Notice

Copy this and send it to your AI assistant to learn