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

Czym jest Edge Runtime w Next.js?

Runtime określa zestaw API dostępnych podczas wykonywania kodu serwerowego. W Next.js masz dwa podstawowe warianty: Node.js oraz Edge Runtime, czyli środowisko oparte na standardach webowych, takich jak fetch, Request, Response, URL, Streams API i Web Crypto.

Next.js pozwala ustawić runtime w page.tsx, layout.tsx i route.ts przez statyczny eksport konfiguracji. Domyślnie używa Node.js. Edge włączasz punktowo tam, gdzie cały graf importów jest z nim zgodny i pomiar potwierdza korzyść.

Kontekst rynkowy mocno się zmienił. Edge kusił głównie bardzo szybkim startem, ale Fluid Compute ograniczył część problemów funkcji Node.js, między innymi przez współdzielenie instancji przez równoległe wywołania. Aktualna dokumentacja Next.js rekomenduje Node.js do renderowania, a Vercel rekomenduje migrację funkcji z Edge do Node.js, gdy zależy Ci na wydajności i niezawodności. Edge pozostał narzędziem specjalistycznym, a nie trybem turbo dla całej aplikacji.

Edge Runtime, CDN i sposób renderowania to trzy różne decyzje

Te pojęcia bywają wrzucane do jednego worka, co prowadzi do złych projektów:

• Runtime mówi, gdzie i z jakimi API wykona się kod serwerowy.
• Strategia renderowania określa, czy wynik powstaje podczas buildu, po nadejściu requestu, czy jest okresowo odświeżany.
• CDN przechowuje gotową odpowiedź blisko użytkownika i często nie wykonuje przy tym Twojego kodu.

Statyczna strona wygenerowana podczas buildu może trafić do globalnego CDN bez Edge Runtime. Route Handler działający na Edge może z kolei zwracać dynamiczną odpowiedź bez cache. Możesz też uruchomić Node.js obok bazy, a gotowy rezultat cache'ować globalnie. Najpierw usuń zbędne wykonanie kodu, potem skracaj drogę tego kodu do użytkownika.

Edge Runtime vs Node.js Runtime: gdzie naprawdę się różnią?

Jak włączyć Edge Runtime w Next.js?

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' },
  })
}

Edge Runtime w stronach Next.js

Ten sam eksport działa w plikach page.tsx i layout.tsx, ale używaj go oszczędnie. Konfiguracja layoutu obejmuje jego segment i potomków, więc jeden eksport może przenieść na Edge znacznie większą część aplikacji, niż sugeruje lokalizacja pliku. Wartość musi być statycznie analizowalna przez Next.js.

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 Next.js 16 dochodzi jeszcze jedna granica: po włączeniu cacheComponents: true nie możesz używać runtime = 'edge' dla takich tras. Cache Components, dyrektywa use cache i powiązane API zakładają runtime Node.js.

Edge Runtime w Proxy, dawniej middleware

Przez długi czas middleware (middleware.ts) domyślnie działało na Edge Runtime. Jeszcze w Next.js 15.5 uzyskało stabilną obsługę Node.js. W Next.js 16 konwencja została przemianowana na proxy.ts, a nowe proxy działa w runtime Node.js i nie pozwala ustawić opcji runtime. Jeśli chcesz zobaczyć, do czego ta warstwa się przydaje, zebrałem przykłady w artykule o zastosowaniach proxy w Next.js.

Proxy działa przed dopasowaniem i renderowaniem tras, dlatego łatwo umieścić w nim zbyt dużo pracy. Framework rekomenduje traktowanie tej warstwy jako ostateczności. Użyj wąskiego matcher, ogranicz liczbę wywołań sieciowych i przekazuj wynik dalej przez nagłówki, cookie, rewrite albo URL. Pełne pobieranie profilu użytkownika z bazy przy każdym zasobie to prosta droga do zwiększenia TTFB całej aplikacji.

Edge czy Node.js: szybka macierz wyboru runtime

Kiedy Edge Runtime ma sens w Next.js?

Zacznij od przepływu danych, nie od mapy użytkowników. Dla każdej operacji rozpisz cztery punkty: miejsce wejścia requestu, lokalizację funkcji, położenie danych i miejsce wykonania następnego kroku. Edge daje przewagę dopiero wtedy, gdy skraca cały krytyczny łańcuch.

Przykład: użytkownik z Tokio trafia do funkcji Edge w Japonii, która trzy razy odpytuje PostgreSQL w Europie. Każde zapytanie pokonuje długą trasę sieciową, a całość może działać wolniej niż pojedyncza funkcja Node.js uruchomiona obok bazy. Jeśli Edge podejmuje decyzję wyłącznie na podstawie cookie i globalnego magazynu feature flag, zysk jest realny, bo odpowiedź nie wraca do odległego originu.

1. Personalizacja treści na podstawie geolokacji

Na platformie udostępniającej geolokalizację funkcja Edge może odczytać kraj lub region użytkownika blisko miejsca wejścia requestu. Sprawdza się to przy wyborze waluty, wariantu językowego lub najbliższego oddziału, o ile nie traktujesz lokalizacji z IP jako twardego dowodu. Nagłówki geolokalizacyjne są zależne od hostingu, mogą nie istnieć lokalnie i powinny mieć bezpieczną wartość domyślną.

Cenę produktu trzymaj w źródle prawdy, a geolokalizacją wybieraj właściwy cennik. Kraj wywnioskowany z IP może być błędny przez VPN, sieć firmową albo operatora komórkowego.

// 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 testy A/B na edge

Decyzja o wariancie powinna zapaść przed renderowaniem i pozostać stabilna dla tego samego użytkownika. Edge jest dobrym miejscem, gdy odczytujesz flagę z globalnego magazynu albo wyliczasz wariant lokalnie z deterministycznego hasha.

// app/api/feature-flags/route.ts
export const runtime = 'edge'
 
export async function GET(request: Request) {
  const visitorId = await getVerifiedVisitorId(request)
 
  return Response.json({
    newCheckout: await isInExperiment(visitorId),
  })
}

W realnym kodzie getVerifiedVisitorId() powinno odczytać podpisaną sesję lub cookie, a isInExperiment() deterministycznie przypisać wariant na podstawie identyfikatora. Nie ufaj identyfikatorowi przesłanemu w dowolnym nagłówku przez klienta. Sam Route Handler z przykładu jest osobnym endpointem i nie przechwytuje renderu strony. Wynik musisz wykorzystać w aplikacji lub wykonać rewrite w warstwie, która faktycznie poprzedza renderowanie. W Next.js 16 taką rolę pełni proxy.ts, działające na Node.js.

3. Proste API proxy i transformacje odpowiedzi

Edge nadaje się na cienką fasadę dla zewnętrznego API, ponieważ może dodać nagłówki, przekształcić małą odpowiedź i zatrzymać klucz po stronie serwera. Największy zysk pojawia się wtedy, gdy upstream również jest globalny albo znajduje się blisko funkcji. Centralne API w jednym regionie ponownie uruchamia problem grawitacji danych.

// 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 url = new URL(process.env.WEATHER_API_URL!)
  url.searchParams.set('city', city)
 
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.WEATHER_API_KEY}` },
  })
 
  if (!response.ok) {
    return Response.json({ error: 'Weather service failed' }, { status: 502 })
  }
 
  const data = await response.json()
 
  return Response.json(
    { city, temp: data.current.temp_c },
    { headers: { 'Cache-Control': 'public, s-maxage=300' } },
  )
}

4. Walidacja JWT i rate limiting na edge

Szybka walidacja podpisu tokenu i limitowanie requestów pasują do Edge, jeśli chroniony endpoint także działa w tej trasie albo żądanie zostaje poprawnie przekazane dalej. Do weryfikacji JWT użyj lekkiej biblioteki jose, która korzysta z Web Crypto (npm install jose). Samą strategię limitowania rozwijam w osobnym artykule o rate limitingu w Next.js z Upstash, gdzie 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 {
    const token = authHeader?.startsWith('Bearer ')
      ? authHeader.slice('Bearer '.length)
      : ''
    await jwtVerify(token, secret, {
      algorithms: ['HS256'],
      issuer: 'https://auth.example.com',
      audience: 'strivelab-api',
    })
  } catch {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }
 
  return Response.json({ ok: true })
}

Walidacja podpisu to tylko część autoryzacji. Biblioteka sprawdzi czas wygaśnięcia, jeśli token zawiera exp, ale nadal musisz zdefiniować oczekiwanego wydawcę, odbiorcę i dozwolony algorytm. Decyzję o dostępie do konkretnego rekordu podejmuj w warstwie, która zna dane domenowe.

5. Dynamiczne OG Images

ImageResponse z next/og używa Satori i Resvg do zamiany JSX oraz ograniczonego podzbioru CSS na PNG. Starsze materiały wymagały Edge Runtime, ale aktualny Next.js obsługuje również Node.js. Edge pasuje do lekkiego obrazu z danymi pobieranymi przez fetch. Node wybierz, gdy chcesz czytać lokalne fonty i grafiki przez node:fs albo korzystasz z zależności niezgodnych z Edge. Pełny wzorzec 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?

Node.js jest właściwym punktem wyjścia dla większości aplikacji. Zmieniaj runtime dopiero wtedy, gdy konkretna trasa ma mały graf zależności, wykonuje krótką pracę i zyskuje na geograficznym rozproszeniu.

• Potrzebujesz API systemowych. fs, path i child_process nie są dostępne na Edge. Pamiętaj, że hosting serverless może ograniczać zapis nawet w Node.js, zwykle do katalogu tymczasowego.

• Korzystasz z ORM z connection pool. Typowe konfiguracje Prisma, Sequelize i TypeORM używają sterowników TCP lub natywnych elementów środowiska Node.js.

• Graf zależności przekracza limit platformy. Na Vercel skompresowany bundle funkcji Edge może mieć 1 MB na Hobby, 2 MB na Pro i 4 MB na Enterprise. Inni dostawcy stosują własne progi.

• Potrzebujesz ISR, Cache Components albo use cache. Edge Runtime nie obsługuje Incremental Static Regeneration, więc dla stron z odświeżaniem statycznego HTML zostajesz przy Node.js. Cache Components w Next.js 16 również wymagają Node.js.

• Potrzebujesz natywnych modułów Node.js. Przykłady obejmują część trybów sharp, bcrypt oraz pakiety z natywnymi bindingami.

• Operacja intensywnie używa CPU lub pamięci. Ciężkie obliczenia, przetwarzanie dużych plików i kompresja źle pasują do restrykcyjnych limitów Edge.

• Łączysz się bezpośrednio z bazą przez TCP. Klasyczne sterowniki PostgreSQL i MySQL wymagają Node.js albo warstwy dostępowej zgodnej z Edge.

• Biblioteka używa require, eval lub new Function. Edge wymaga modułów ESM, a dynamiczna ewaluacja kodu jest zablokowana. Problem może ukrywać się w zależności pośredniej, której nie importujesz świadomie.

Jak sprawdzić zgodność pakietu z Edge Runtime?

Napis „isomorphic” w README pakietu nie jest gwarancją. Biblioteka może mieć osobny entrypoint dla przeglądarki, lecz jej wariant serwerowy nadal importować node:crypto, buforować pliki albo generować funkcje w locie. Sprawdź cały graf zależności w produkcyjnym buildzie.

Najbardziej praktyczna procedura wygląda tak:

1. Dodaj export const runtime = 'edge' tylko w docelowej trasie.
2. Uruchom next build, bo część konfliktów wyjdzie dopiero podczas bundlowania.
3. Przejdź krytyczne ścieżki w next dev i w podglądowym deploymencie.
4. Sprawdź logi pod kątem importów API Node.js oraz błędów dynamicznej ewaluacji.
5. Zmierz rozmiar gotowej funkcji, liczbę połączeń wychodzących i odpowiedź p95.

unstable_allowDynamic potrafi uciszyć błąd buildu dla wskazanych plików, lecz nie dodaje obsługi eval do runtime'u. Jeżeli taka instrukcja zostanie wykonana, funkcja nadal zakończy się błędem. Traktuj tę opcję jako precyzyjny wyjątek dla martwej gałęzi kodu, nie jako polyfill.

Bazy danych zgodne z Edge Runtime

Jeśli chcesz łączyć się z bazą z Edge, wybierz usługę i konkretny sterownik, które komunikują się przez API dostępne w danym runtime. Sama marka bazy nie gwarantuje zgodności. Ten sam PostgreSQL może być obsługiwany przez klasyczny sterownik TCP w Node.js albo przez driver HTTP przygotowany dla Edge.

• Neon udostępnia serverless driver korzystający z HTTP lub WebSocket.
• PlanetScale ma driver oparty na fetch.
• Upstash Redis udostępnia REST API zamiast protokołu TCP Redisa.
• Turso oferuje zdalny dostęp przez libSQL.
• Supabase pozwala korzystać z PostgREST przez supabase-js.

Każdy dodatkowy request do bazy podnosi opóźnienie. Łącz zapytania, unikaj sekwencyjnych odczytów i kontroluj liczbę połączeń. Na Vercel pojedyncze wywołanie funkcji Edge może utrzymywać ograniczoną liczbę równoległych połączeń, więc nieograniczone Promise.all nie zmieni sieci w autostradę.

// 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: Edge Runtime i Node.js w jednym projekcie

Oba runtime'y mogą działać w jednym projekcie. Nie oznacza to, że każda aplikacja potrzebuje hybrydy. Jeśli Node.js spełnia budżet wydajnościowy, dodatkowy runtime zwiększy powierzchnię testów, liczbę wariantów zależności i złożoność obserwacji produkcji. Edge dołącz tam, gdzie rozwiązuje zmierzony problem.

Request
  ├── statyczny asset lub HTML → CDN, bez uruchamiania funkcji
  └── Proxy na Node.js → rewrite, redirect lub przekazanie requestu
        ├── Route Handler na Edge → lekka logika oparta na Web API
        ├── Route Handler na Node.js → ORM, płatności, pliki
        └── strona na Node.js → Server Components, cache, streaming

Trasy mogą deklarować własny runtime, z uwzględnieniem konfiguracji dziedziczonej z layoutów. Tę samą filozofię ograniczania pracy wykonywanej dla requestu realizuje Partial Prerendering, które w modelu Cache Components wymaga Node.js.

Jak zmierzyć, czy Edge rzeczywiście przyspiesza aplikację?

Lokalny benchmark nie odpowie na pytanie o globalne opóźnienia, bo omija sieć, regionalne rozmieszczenie funkcji i odległość do danych. Przygotuj dwie możliwie identyczne trasy, jedną na Node.js, drugą na Edge, a następnie testuj je z tych samych lokalizacji i na tej samej wersji deployu.

Nie ograniczaj pomiaru do średniej. Zbierz:

• TTFB oraz pełny czas odpowiedzi dla p50, p95 i p99,
• czas każdego wywołania bazy, cache i zewnętrznego API,
• wyniki po okresie bezczynności oraz pod stałym ruchem,
• region wykonania funkcji i region źródła danych,
• liczbę błędów, timeoutów, ponowień oraz koszt dla reprezentatywnego ruchu.

Nagłówek Server-Timing pozwala oddzielić pracę aplikacji od czasu spędzonego w sieci. Możesz dodać go w obu wariantach bez zewnętrznej biblioteki:

export async function GET() {
  const startedAt = performance.now()
  const data = await fetchInventory()
  const duration = performance.now() - startedAt
 
  return Response.json(data, {
    headers: {
      'Server-Timing': `inventory;dur=${duration.toFixed(1)}`,
    },
  })
}

Porównuj cały request, nie sam start funkcji. Jeśli Edge oszczędza 30 ms na uruchomieniu, ale dodaje 120 ms przez odległą bazę, decyzja jest oczywista. Jeśli lekka funkcja kończy pracę lokalnie i nie dotyka originu, wtedy szybki start oraz bliskość użytkownika mogą wyraźnie obniżyć p95.

Deployment decyduje o znaczeniu słowa „edge”

Next.js opisuje dostępne API, lecz to adapter i platforma wybierają regiony, limity, sposób cache'owania oraz semantykę zmiennych środowiskowych. Na Vercel funkcja Edge domyślnie trafia blisko przychodzącego requestu, a preferredRegion pozwala ograniczyć wykonanie do wskazanych regionów. Na innym hostingu ta sama konfiguracja może zachowywać się inaczej albo nie być obsługiwana.

Przed migracją sprawdź również monitoring. Streaming jest obsługiwany przez oba runtime'y, jeśli zapewnia go adapter, ale integracje obserwowalności nie muszą mieć parytetu. Przykładowo Vercel dokumentuje brak wsparcia OpenTelemetry dla funkcji Edge. Różnica w kilku milisekundach nie zrekompensuje utraty śladów, których zespół potrzebuje podczas awarii.