Netlify Integration

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

1. 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" }),
    };
  }
};

2. 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;
};

3. Essential netlify.toml for Next.js

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

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

# OpenNext adapter auto-detects Next.js — no plugin entry needed.
# Legacy: @netlify/plugin-nextjs is replaced by @opennextjs/netlify.

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

4. 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.

5. 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)

6. 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...
}

7. 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}` };
  }
};

8. 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
};

9. Dynamic Base URL Detection

function getBaseUrl(req: NextApiRequest): string {
  const proto = (req.headers['x-forwarded-proto'] as string) || 'https';
  const host = (req.headers['x-forwarded-host'] as string) || (req.headers.host as string);
  return `${proto}://${host}`;
}

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

10. 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

• Powered by the open-source OpenNext adapter (@opennextjs/netlify), which replaced the legacy @netlify/plugin-nextjs as the canonical approach
• Supports Next.js 13.5+ through 16, including App Router, Server Components, and Streaming
• Handles ISR, SSR, static generation, and fine-grained edge caching automatically
• API routes automatically converted to serverless functions
• Custom functions go in .netlify/functions/ (separate from pages/api/)
• The adapter auto-updates on each build unless you pin a version in package.json

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 on Netlify via OpenNext adapter: App Router, ISR, SSR, skew protection, image 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:

1. 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

2. 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

3. 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:

1. 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

2. 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)

3. 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:

1. 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)

2. 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

3. Advanced debugging:

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

4. 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

1. 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
   

2. 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

3. Set environment variables:

   netlify env:set VARIABLE_NAME value
   # Or use Netlify Dashboard: Site Settings → Environment Variables
   

4. Deploy:

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

Fixing Webhook Timeout Issues

Symptom: 60% message loss, 504 Gateway Timeout errors

Solution:

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

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

Debugging Function Errors

1. Check function logs:

   netlify functions:log function-name --stream
   

2. Add structured logging:

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

3. Test locally:

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

4. Review common issues:

   • See references/debugging.md for comprehensive troubleshooting guide

Version History

• v2.1 (2026-04-21) - Updated for OpenNext adapter (replaces legacy @netlify/plugin-nextjs), Next.js 16 support, fine-grained edge caching
• 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