Performance: Deploying Routes to the Edge Runtime

Performance: Deploying Routes to the Edge Runtime (PERF-21)

Overview

Next.js supports multiple runtime targets for API route handlers: Node.js (the default) and Edge. The edge runtime runs your code in a globally distributed, V8-based environment with no cold starts and minimal overhead. For simple, stateless endpoints this is a significant performance improvement over standard serverless Node.js functions.

This page describes which routes in the platform are appropriate for edge runtime, how to configure them, and what constraints apply.

When to Use Edge Runtime

Use export const runtime = 'edge' on a route when all of the following are true:

The handler is stateless (no session state held between requests).
It does not import Node.js-only APIs (e.g. fs, crypto from node:crypto, net).
It does not use the Neon HTTP driver or any other database client that requires the Node.js runtime.
The response logic is lightweight — simple JSON responses, token validation, or signature verification.

Recommended Edge-Runtime Routes

`/api/health`

The health-check endpoint is the simplest candidate. It requires no database access, no authentication, and returns a static JSON response. Deploying it to the edge ensures monitoring systems and load balancers receive near-instant responses from the closest available node.

// src/app/api/health/route.ts
export const runtime = 'edge';

export async function GET() {
  return Response.json({ status: 'ok' });
}

Owner Portal Token Validation (`GET /portal/[token]`)

When an owner accesses their self-service portal via a token link, the initial token validation step is a lightweight lookup. If implemented as a dedicated route handler (separate from DB-heavy tRPC procedures), this route is a strong candidate for edge deployment — particularly beneficial because Irish property owners may access the portal from varying geographic locations.

// src/app/api/portal/[token]/route.ts  (example structure)
export const runtime = 'edge';

export async function GET(
  _request: Request,
  { params }: { params: { token: string } }
) {
  const { token } = params;
  // Lightweight validation — e.g. JWT verification using Web Crypto API
  // Do NOT import Neon or any Node.js-only driver here
}

Note: If the portal data fetch (owner.getPortalData) uses the Neon HTTP driver via tRPC, keep that procedure on the Node.js runtime. Only move the thin token-validation layer to edge.

Webhook Receivers (Stateless Validation Layer)

Webhook endpoints that verify an HMAC signature before forwarding to a queue are also suitable for edge runtime, as signature verification uses only the Web Crypto API.

Routes That Must Stay on Node.js Runtime

Route Pattern	Reason
All DB-backed tRPC procedures	Use the Neon HTTP driver, which requires Node.js
Any route importing `node:*` built-ins	Edge runtime does not expose the Node.js standard library
Routes using large npm packages with native bindings	Not supported in the V8 edge sandbox

Do not add export const runtime = 'edge' to tRPC route handlers (e.g. src/app/api/trpc/[trpc]/route.ts) that serve DB-heavy procedures — doing so will cause runtime errors when the Neon driver attempts to use Node.js APIs unavailable in the edge sandbox.

How to Add the Declaration

Open the route handler file (e.g. src/app/api/health/route.ts).
Add the export at the top of the file, before any handler functions:

export const runtime = 'edge';

Ensure no imports in that file (or its transitive dependencies) rely on Node.js-only APIs.
Deploy and verify the route appears under the Edge Functions section of your Vercel project dashboard.

Testing Edge Routes Locally

Next.js development server (next dev) simulates the edge runtime locally. If a route declares runtime = 'edge' but imports a Node.js-only module, you will see an error in the terminal at request time:

Error: The edge runtime does not support Node.js APIs.

Fix by removing the incompatible import or moving the logic back to the Node.js runtime.