Contentful Personalization & Analytics

Next.js SDK App Router Edge Runtime Reference Implementation

Reference implementation for actual Edge runtime handoff routes in @contentful/optimization-nextjs. Routes export runtime = 'edge', avoid Node-only APIs, and use @contentful/optimization-nextjs/edge from @/lib/edge-optimization.

This implementation is separate from the App Router Cache Components reference implementation. It does not cover ISR, route-level revalidate, or Cache Components.

What this covers

• Request-personalized Edge runtime handoff from app/edge-request/route.ts
• Public permutation Edge runtime handoff from app/edge-selection/[segment]/route.ts
• Edge runtime assertion with globalThis.EdgeRuntime === 'edge-runtime'
• Browser handoff state created without Node-only APIs

Prerequisites

• Node.js >= 20.19.0 (24.15.0 recommended to match .nvmrc)
• pnpm

Setup

Run these commands from the monorepo root:

pnpm install
pnpm build:pkgs
pnpm implementation:run -- nextjs-sdk_app-router_edge-runtime implementation:install
Copy

Running locally

Run these commands from the monorepo root:

pnpm implementation:run -- nextjs-sdk_app-router_edge-runtime dev
pnpm implementation:run -- nextjs-sdk_app-router_edge-runtime build
pnpm implementation:run -- nextjs-sdk_app-router_edge-runtime typecheck
pnpm implementation:run -- nextjs-sdk_app-router_edge-runtime lint
Copy

The development server runs on http://localhost:3003.

Running E2E tests

Run the full E2E setup and test suite from the monorepo root:

pnpm setup:e2e:nextjs-sdk_app-router_edge-runtime
pnpm test:e2e:nextjs-sdk_app-router_edge-runtime
Copy

The E2E suite uses the shared lib/e2e-web Edge runtime scenarios with E2E_FLAGS=EDGE.

Related

• Next.js SDK App Router - Cache Components App Router reference implementation
• Next.js SDK Pages Router - Pages Router ISR reference implementation
• @contentful/optimization-nextjs - Next.js SDK package