Edge Runtime w Next.js — kiedy Edge, a kiedy Node?

Czym jest Edge Runtime w Next.js?

Next.js pozwala wybrać runtime niezależnie dla każdego Route Handlera i stron. Domyślny runtime to Node.js — edge włączasz punktowo, w sposób przemyślany, tam gdzie rzeczywiście ma to sens.

Warto przy tym znać szerszy kontekst, ponieważ trochę się pozmieniało. O ile przez lata edge kusił głównie zerowym cold startem, ale dzięki Fluid Compute runtime Node.js stał się optymalnym wyborem dla większości standardowych zastosowań. Edge nie zniknął, ale przestał być bezrefleksyjnym wyborem dla maksymalnej wydajności.

Edge vs Node.js — gdzie naprawdę się różnią

Jak włączyć Edge Runtime

W Route Handlerach

// app/api/hello/route.ts
export const runtime = 'edge'
 
export async function GET() {
  return new Response(JSON.stringify({ message: 'Hello from edge!' }), {
    headers: { 'Content-Type': 'application/json' },
  })
}

W stronach (Page)

Ten sam eksport działa w plikach page.tsx, ale używaj go oszczędnie. Jeśli strona może być statyczna albo korzysta z ISR, Edge Runtime nie jest dobrym domyślnym wyborem — statyczny HTML z CDN zwykle będzie prostszy, tańszy i równie szybki.

W Proxy (dawniej middleware)

Przez długi czas obowiązywała zasada, że middleware (middleware.ts) zawsze działa na Edge Runtime, bez jakiejkolwiek możliwości wyboru. W Next.js 16 plik został przemianowany na proxy.ts, a wraz z tą zmianą proxy działa wyłącznie na runtime Node, a nie na Edge. Jeśli chcesz zobaczyć, do czego ta warstwa się przydaje, zebrałem przykłady w artykule o zastosowaniach proxy w Next.js.

Szybka macierz wyboru runtime

Kiedy edge ma sens — 5 przypadków

1. Personalizacja treści na podstawie geolokacji

Edge widzi lokalizację użytkownika zanim request dotrze do serwera origin. Idealne do wyświetlania lokalnych cen, walut czy najbliższych oddziałów.

// app/api/localized-content/route.ts
export const runtime = 'edge'
 
export async function GET(request: Request) {
  const country = request.headers.get('x-vercel-ip-country') || 'PL'
  return Response.json({
    currency: country === 'US' ? 'USD' : country === 'DE' ? 'EUR' : 'PLN',
  })
}

2. Feature flags i A/B testy

Decyzja o wariancie musi zapaść przed renderowaniem — edge jest szybszy niż round-trip do serwera origin.

// app/api/feature-flags/route.ts
export const runtime = 'edge'
 
export async function GET(request: Request) {
  const userId = request.headers.get('x-user-id') || 'anonymous'
  return Response.json({
    newCheckout: await isInExperiment(userId),
  })
}

W realnym kodzie isInExperiment() powinno być deterministyczne, np. oparte o hash użytkownika albo odpowiedź lekkiego serwisu feature flag. Ważne jest to, że decyzja zapada przed właściwym renderowaniem.

3. Proste API proxy i transformacje odpowiedzi

Edge świetnie nadaje się jako proxy do zewnętrznych API, ponieważ dodaje nagłówki, transformuje odpowiedzi i ukrywa klucze API.

// app/api/weather/route.ts
export const runtime = 'edge'
 
export async function GET(request: Request) {
  const city = new URL(request.url).searchParams.get('city') || 'Krakow'
  const response = await fetch(`${process.env.WEATHER_API_URL}?city=${city}`)
  const data = await response.json()
 
  return Response.json(
    { city, temp: data.current.temp_c },
    { headers: { 'Cache-Control': 'public, s-maxage=300' } },
  )
}

4. Walidacja tokenów JWT i rate limiting

Szybka walidacja tokenów, limitowanie requestów, sprawdzanie uprawnień — zanim request dotrze do Node.js. Do weryfikacji JWT na edge warto użyć (stworzonej do tego celu) lekkiej biblioteki jose (npm install jose). Samą strategię limitowania rozwijam w osobnym artykule o rate limitingu w Next.js z Upstash — tam znajdziesz algorytmy i obsługę awarii Redisa.

// app/api/protected/route.ts
import { jwtVerify } from 'jose'
 
export const runtime = 'edge'
 
export async function POST(request: Request) {
  const authHeader = request.headers.get('authorization')
  const secret = new TextEncoder().encode(process.env.JWT_SECRET!)
  try {
    await jwtVerify(authHeader?.replace('Bearer ', '') ?? '', secret)
  } catch (e) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }
 
  return Response.json({ ok: true })
}

5. Dynamiczne OG images (obrazy social media)

Generowanie obrazów social media na edge, ImageResponse z next/og (następca dawnego @vercel/og) używa Satori pod spodem i działa natywnie na Edge Runtime. Pełny wzorzec generowania podglądów opisałem w artykule o dynamicznych OG images z next/og.

// app/api/og/route.tsx
import { ImageResponse } from 'next/og'
 
export const runtime = 'edge'
 
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const title = searchParams.get('title') || 'StriveLab'
 
  return new ImageResponse(
    <div style={{ fontSize: 60, padding: 80 }}>{title}</div>,
    { width: 1200, height: 630 },
  )
}

Kiedy zostać przy Node.js runtime

Edge nie jest uniwersalnym rozwiązaniem, dlatego warto w określonych sytuacjach zostać przy Node.js runtime. Powody mogą być różne:

• Potrzebujesz dostępu do systemu plików — fs, path, child_process nie są dostępne na edge

• Korzystasz z ORM z connection pool — Prisma (bez Edge Client), Sequelize, TypeORM wymagają trwałych połączeń TCP

• Twój pakiet przekracza limity — edge ma ograniczenie rozmiaru bundla (zwykle 1–4 MB)

• Potrzebujesz ISR lub revalidate — Edge Runtime nie obsługuje Incremental Static Regeneration, więc dla stron z odświeżaniem statycznego HTML-a zostajesz przy Node.js

• Potrzebujesz natywnych modułów Node.js — sharp (przetwarzanie obrazów), bcrypt, natywne bindingi

• Operacje są CPU-intensive — ciężkie obliczenia, parsowanie dużych plików, kompresja

• Łączysz się z bazą przez TCP — tradycyjne bazy (PostgreSQL, MySQL z directem) wymagają Node.js lub dedykowanego HTTP proxy

Bazy danych edge-compatible

Jeśli chcesz łączyć się z bazą z edge, wybierz usługę z HTTP/WebSocket API:

• Neon — serverless Postgres z HTTP driverem,
• PlanetScale — serverless MySQL z fetch API,
• Upstash Redis — Redis over HTTP,
• Turso — SQLite na edge (libSQL),
• Supabase — Postgres z REST API (supabase-js działa na edge).

// Edge-compatible: Neon z HTTP driverem
import { neon } from '@neondatabase/serverless'
 
export const runtime = 'edge'
 
export async function GET() {
  const sql = neon(process.env.DATABASE_URL!)
  const posts = await sql`SELECT * FROM posts ORDER BY created_at DESC LIMIT 10`
  return Response.json(posts)
}

Architektura hybrydowa — najlepsze z dwóch światów

Tak, łączenie ze sobą obu jest najlepszym rozwiązaniem. Właśnie najlepsze aplikacje Next.js czerpią z zalet obu runtime'ów. Edge jest kierowany do lekkich operacji globalnych, a Node.js do renderowania, ISR, integracji z bazą i cięższego przetwarzania.

Request → Proxy (Node: routing, auth, rewrite, redirect)
       ↓
       ├── Edge Route Handler (API proxy, feature flags, OG images)
       │
       └── Node.js Route Handler (ORM, file processing, heavy compute)
              ↓
           Server Component (rendering z pełnym Node.js API)

Każdy route może niezależnie deklarować swój runtime i nie musisz wybierać jednego dla całej aplikacji. Tę samą filozofię łączenia statyki z dynamiką na poziomie pojedynczej strony realizuje Partial Prerendering, które warto poznać obok podziału na runtime'y.