Choosing Between Netlify Functions and Edge Handlers for Dynamic Request Logic

Decision Context

When you need to run custom code in response to HTTP requests on a Netlify‑hosted site, you can either use Netlify Functions or Netlify Edge Handlers. Both are serverless‑style solutions, but they differ in where the code executes, how long it can run, what resources it can access, and how it is billed. The right choice depends on the nature of the logic you need to perform and the performance characteristics you care about.

Comparison Table

Feature	Netlify Functions	Netlify Edge Handlers
Runtime environment	AWS Lambda (Node.js 18+), full NPM ecosystem	Netlify CDN edge, JavaScript/TypeScript compiled to WebAssembly
Cold start latency	Up to 300 ms, mitigated by warm‑up tricks	None – always warm at the edge
Maximum execution time	10 s	10 s
Request/Response size limit	10 MB	1 MB
Background/long‑running tasks	Supported (e.g., via SNS, SQS, or external queues)	Not supported – must finish within the request cycle
Environment variables	Runtime access, can change without rebuild	Compiled‑time injection, rebuild required for changes
Cost model	Per invocation and compute time (pay‑as‑you‑go)	Included in Netlify CDN plan, no per‑request cost
File system access	Read/write to /tmp (ephemeral)	No file system access

Trade‑Offs

• Latency vs. Flexibility: Edge Handlers give sub‑10 ms edge latency but are limited to lightweight logic. Functions can do heavy work or use external libraries but may suffer from cold starts.
• Payload Size: If you need to handle large uploads or binary data, Functions are the only viable option due to the 1 MB edge limit.
• Runtime Features: Functions support Node.js features like streams, child processes, and a wide array of npm packages. Edge Handlers run in a sandboxed WebAssembly environment, so you need to use the built‑in fetch API for external calls.
• Cost Sensitivity: For high‑traffic sites where every millisecond counts, Edge Handlers can reduce per‑request cost. If you need complex processing, the compute cost of Functions may be acceptable.
• Environment Variable Management: If you change configuration frequently, Functions are easier to manage because you can update variables in Netlify’s UI or CLI without rebuilding.

Concrete Implementation

Minimal Function – /api/hello

Create netlify/functions/hello.js:

exports.handler = async function(event, context) {
  console.log('Request received:', event.path);
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Hello from a Netlify Function' }),
    headers: { 'Content-Type': 'application/json' }
  };
};

Deploy locally with netlify dev or to production with netlify deploy --prod. The Function will be available at /api/hello.

Minimal Edge Handler – /headers

Create netlify/edge-handlers/headers.js:

export default async function handler(request) {
  const response = await fetch(request);
  // Add a custom header before returning
  const newHeaders = new Headers(response.headers);
  newHeaders.set('X‑Edge‑Handled', 'true');
  return new Response(response.body, { status: response.status, headers: newHeaders });
}

Edge Handlers are automatically routed by Netlify when you place them under netlify/edge-handlers. The handler will run for any request that matches the file path (e.g., /headers).

Testing and Validation

1. Deploy both pieces to a preview branch.
2. Use curl -I https://preview-url/headers to verify the custom header and measure latency. The curl -w '%{time_total}\n' flag can capture total round‑trip time.
3. Send a POST request with a 2 MB payload to /api/hello and observe that the Function accepts it. Then try the same payload to /headers and confirm it fails with a 413 response.
4. Check Netlify logs for the Function: netlify logs --type functions. Look for the first invocation to see if a cold start is logged (typically a longer latency on the first request).
5. Review the build log for the Edge Handler. Environment variables defined in netlify.toml or via the UI are baked into the compiled bundle; a change requires a rebuild.

Practical Decision Checklist

• Do you need to process payloads >1 MB? Choose Functions.
• Is the logic purely request/response transformation with no heavy CPU work? Edge Handlers are preferable.
• Will you frequently change environment variables? Functions offer easier runtime updates.
• Do you care about per‑request cost and want to keep the edge cost flat? Edge Handlers are included in the CDN plan.
• Do you need to run background jobs or heavy processing? Functions (or an external worker) are required.

Limitations and Next Steps

• Edge Handlers cannot perform CPU‑intensive tasks or write to disk. If your logic expands, consider refactoring to a Function.
• Functions may suffer from cold starts on low traffic sites. Use the netlify.toml functions: { warmup: true } trick or a scheduled ping to keep them warm.
• Both options share a 10‑second max execution time. For longer jobs, offload to an external service or queue.
• When using Edge Handlers, remember that environment variables are static at compile time; rebuild to apply changes.

By mapping your use case against the constraints above, you can confidently select the right Netlify feature for dynamic request logic.