Jaka jest różnica między runtime Edge i Node.js?

Question

Accepted Answer

Next.js może uruchamiać kod serwera w dwóch runtime'ach. **Runtime Node.js** (domyślny) to pełne środowisko Node; **runtime Edge** to lekkie, oparte na V8 środowisko, które działa w rozproszonych na całym świecie lokalizacjach edge'u blisko użytkowników.

## Dlaczego to ważne

```ts
// per route handler / page
export const runtime = "edge";   // or "nodejs" (the default)
```

## Kompromisy

```text
                  Node.js runtime         Edge runtime
────────────────────────────────────────────────────────────────
APIs              full Node (fs, crypto,  Web APIs only (fetch,
                  Buffer, native modules) Request/Response) — limited
npm packages      all                     only those without Node APIs
Cold start        slower, heavier         near-zero, lightweight
Location          regional (one region)   global (near the user)
Latency to user   higher if far away      very low (geo-distributed)
Execution limits  longer, more memory     short CPU time, less memory
Database          direct TCP connections  HTTP-based DBs only (no raw TCP)
```

## Kiedy używać Edge

```text
✓ Middleware (auth checks, redirects, geo-routing) — must be fast & global
✓ Simple, latency-sensitive endpoints (personalization, A/B, feature flags)
✓ Reading geolocation/headers to tailor responses
```

Edge sprawdza się w przypadku **lekkiej logiki, która korzysta z bycia blisko użytkownika** i błyskawicznych zimnych startów.

## Kiedy używać Node.js

```text
✓ Direct database connections (Prisma over TCP, etc.)
✓ Heavy computation, large dependencies, native modules
✓ Anything using Node-specific APIs (fs, crypto.randomBytes via Node, Buffer)
```

## Rzeczywisty przykład ograniczenia

```ts
export const runtime = "edge";
import fs from "fs";           // ❌ not available on Edge — build/runtime error
import { PrismaClient } from "@prisma/client"; // ⚠️ needs HTTP/data-proxy on Edge
```

Wiele popularnych bibliotek (w tym ORMy otwierające surowe sockety BD) nie działa na Edge bez adaptera opartego na HTTP — częsta pułapka.

## Dlaczego to ważne

Wybór runtime'u to naprawdę architekturalna decyzja: **Edge** do szybkiej, globalnej, lekkiej logiki (szczególnie middleware'u) z minimalnymi chłodnymi startami, **Node.js** do pełnego dostępu API, bezpośrednich połączeń BD i ciężkiej pracy.

Znajomość ograniczeń Edge'a (tylko Web API, brak surowego TCP, krótka egzekucja) zapobiega częstemu błędowi polegającemu na umieszczaniu kodu obciążonego bazą danych lub zależnego od Node'a na runtime'ie, który go nie może obsługiwać.