Edge API Routes (Beta)

Edge API Routes enable you to build high performance APIs with Next.js. Using the Edge Runtime, they are often faster than Node.js-based API Routes. This performance improvement does come with constraints, like not having access to native Node.js APIs. Instead, Edge API Routes are built on standard Web APIs.

Any file inside the folder pages/api is mapped to /api/* and will be treated as an API endpoint instead of a page. They are server-side only bundles and won’t increase your client-side bundle size.

Examples

Basic

export const config = {
  runtime: 'experimental-edge',
}
export default (req) => new Response('Hello world!')

JSON Response

import type { NextRequest } from 'next/server'
export const config = {
  runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
  return new Response(
    JSON.stringify({
      name: 'Jim Halpert',
    }),
    {
      status: 200,
      headers: {
        'content-type': 'application/json',
      },
    }
  )
}

Cache-Control

import type { NextRequest } from 'next/server'
export const config = {
  runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
  return new Response(
    JSON.stringify({
      name: 'Jim Halpert',
    }),
    {
      status: 200,
      headers: {
        'content-type': 'application/json',
        'cache-control': 'public, s-maxage=1200, stale-while-revalidate=600',
      },
    }
  )
}

Query Parameters

import type { NextRequest } from 'next/server'
export const config = {
  runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
  const { searchParams } = new URL(req.url)
  const email = searchParams.get('email')
  return new Response(email)
}

Forwarding Headers

import { type NextRequest } from 'next/server'
export const config = {
  runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
  const authorization = req.cookies.get('authorization')
  return fetch('https://backend-api.com/api/protected', {
    method: req.method,
    headers: {
      authorization,
    },
    redirect: 'manual',
  })
}

Differences between API Routes

Edge API Routes use the Edge Runtime, whereas API Routes use the Node.js runtime.

Edge API Routes can stream responses from the server and run after cached files (e.g. HTML, CSS, JavaScript) have been accessed. Server-side streaming can help improve performance with faster Time To First Byte (TTFB).

View the supported APIs and unsupported APIs for the Edge Runtime.