@beignet/next 0.0.26 → 0.0.28

package/README.md

@@ -122,47 +122,46 @@ export const contracts = contractsFromRoutes(routes);
 
 ```typescript
 // server/index.ts
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import type { AppContext } from "@/app-context";
 import { routes } from "@/server/routes";
 
-export const server = await createNextServer<AppContext>({
-  ports: {},
-  routes,
-  context: async ({ req }) => {
-    // DEMO ONLY: this reads an unauthenticated header to simulate identity.
-    // Real applications should verify a signed token or session cookie first.
-    return {
-      userId: req.headers.get("x-user-id") || "anonymous",
-    };
-  },
-  mapUnhandledError: () => ({
-    status: 500,
-    body: {
-      code: "INTERNAL_SERVER_ERROR",
-      message: "Internal server error",
+export const getServer = createNextServerLoader(() =>
+  createNextServer<AppContext>({
+    ports: {},
+    routes,
+    context: async ({ req }) => {
+      // DEMO ONLY: this reads an unauthenticated header to simulate identity.
+      // Real applications should verify a signed token or session cookie first.
+      return {
+        userId: req.headers.get("x-user-id") || "anonymous",
+      };
     },
+    mapUnhandledError: () => ({
+      status: 500,
+      body: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Internal server error",
+      },
+    }),
   }),
-});
+);
 ```
 
 ### 5. Set up routes
 
 Expose ordinary application routes through one catch-all framework route. Next
-App Router requires literal named exports for each HTTP method, so assign the
-central `server.api` handler to every verb your API should accept:
+App Router imports route modules during production builds, so keep server boot
+behind the memoized `getServer` loader and expose literal named exports with
+`createApiRoute`:
 
 ```typescript
 // app/api/[[...path]]/route.ts
-import { server } from "@/server";
-
-export const DELETE = server.api;
-export const GET = server.api;
-export const HEAD = server.api;
-export const OPTIONS = server.api;
-export const PATCH = server.api;
-export const POST = server.api;
-export const PUT = server.api;
+import { createApiRoute } from "@beignet/next";
+import { getServer } from "@/server";
+
+export const { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT } =
+  createApiRoute(getServer);
 ```
 
 This catch-all file is Next.js adapter glue. It forwards requests to the
@@ -179,13 +178,13 @@ as webhooks, redirects, downloads, or adapter-specific glue:
 ```typescript
 // app/api/webhooks/payments/route.ts
 import { handlePaymentWebhookUseCase } from "@/features/billing/use-cases";
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { createPaymentWebhookRoute } from "@beignet/next";
 
 export const runtime = "nodejs";
 
 export const { POST } = createPaymentWebhookRoute({
-  server,
+  server: getServer,
   handle: async ({ ctx, event }) => {
     await handlePaymentWebhookUseCase.run({ ctx, input: event });
     return { status: 200, body: { received: true } };
@@ -202,7 +201,7 @@ validates the typed event catalog before your app handles the event.
 
 ```typescript
 export const { POST } = createWebhookRoute({
-  server,
+  server: getServer,
   webhook: providerWebhook,
   handle: async ({ ctx, event }) => {
     await handleProviderEventUseCase.run({ ctx, input: event.payload });
@@ -214,21 +213,27 @@ export const { POST } = createWebhookRoute({
 For downloads, plain text, and redirects, return a native web `Response`:
 
 ```typescript
-export const GET = server.route(downloadFile).handle(async () =>
-  new Response(await loadFile(), {
-    headers: { "Content-Type": "application/octet-stream" },
-  }),
-);
+import { getServer } from "@/server";
 
-export const GET = server.route(robotsTxt).handle(async () =>
-  new Response("User-agent: *\nAllow: /\n", {
-    headers: { "Content-Type": "text/plain; charset=utf-8" },
-  }),
-);
+export async function GET(req: Request) {
+  const server = await getServer();
+  const handle = server.route(downloadFile).handle(async () =>
+    new Response(await loadFile(), {
+      headers: { "Content-Type": "application/octet-stream" },
+    }),
+  );
 
-export const POST = server.route(startCheckout).handle(async () =>
-  Response.redirect("https://checkout.example.com/session/123", 303),
-);
+  return handle(req);
+}
+
+export async function POST(req: Request) {
+  const server = await getServer();
+  const handle = server.route(startCheckout).handle(async () =>
+    Response.redirect("https://checkout.example.com/session/123", 303),
+  );
+
+  return handle(req);
+}
 ```
 
 Native `Response` instances intentionally bypass JSON serialization and
@@ -262,29 +267,26 @@ Creates a Next.js server instance with the given options.
 
 ### NextServer methods
 
-#### `server.api`
+#### `createApiRoute(getServer)`
 
-A Next.js handler for routes registered in `server/index.ts`. Framework-style
-apps usually expose it once from a catch-all API route.
+A Next.js catch-all route helper for routes registered in `server/index.ts`.
+Framework-style apps usually expose it once from a catch-all API route.
 
 ```typescript
 // app/api/[[...path]]/route.ts
-import { server } from "@/server";
-
-export const DELETE = server.api;
-export const GET = server.api;
-export const HEAD = server.api;
-export const OPTIONS = server.api;
-export const PATCH = server.api;
-export const POST = server.api;
-export const PUT = server.api;
+import { createApiRoute } from "@beignet/next";
+import { getServer } from "@/server";
+
+export const { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT } =
+  createApiRoute(getServer);
 ```
 
 This route file is not a catch-all contract. Keep contract paths explicit and
 use the file only to expose the central server handler.
 
-Next App Router requires literal named exports for each HTTP method, so assign
-the same `server.api` handler to every verb your API should accept.
+Next App Router requires literal named exports for each HTTP method. The route
+helper keeps those exports literal while deferring provider startup until a
+request arrives.
 
 #### `server.route(contract)`
 
@@ -292,25 +294,74 @@ Returns a route builder for focused per-file handlers such as webhooks,
 redirects, downloads, or other adapter-owned endpoints. Use
 `defineRouteGroup<AppContext>()({ ... })` plus `defineRoutes(...)` for
 ordinary application routes; `server.route(contract).handle(...)` route files
-are not imported by the central `server.api` handler.
+are not imported by the central API handler.
 
 **Returns:** Route builder with:
 - `handle(fn)`: Create a custom handler function
 
 ```typescript
 // app/api/reports/[id]/download/route.ts
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { downloadReport } from "@/features/reports/contracts";
 
-export const GET = server
-  .route(downloadReport)
-  .handle(async ({ ctx, path }) =>
+export async function GET(req: Request) {
+  const server = await getServer();
+  const handle = server.route(downloadReport).handle(async ({ ctx, path }) =>
     new Response(await ctx.ports.reports.loadBytes(path.id), {
       headers: { "Content-Type": "application/pdf" },
     }),
   );
+
+  return handle(req);
+}
 ```
 
+#### `server.rawRoute(init)`
+
+Builds a handler for a route that cannot be a contract — third-party callback
+endpoints with externally defined request shapes, signature-verified
+webhooks, streaming endpoints — that still runs the whole server pipeline:
+correlation, hooks (rate limiting, idempotency, CORS, logging, error
+reporting), context creation, instrumentation, and framework error mapping.
+Request parsing and validation are skipped and the request body is left
+unconsumed, so the handler owns body reading.
+
+`init.name`, `init.method`, and `init.path` identify the route to hooks,
+instrumentation, and devtools — routing itself belongs to the route file
+that mounts the handler. `init.metadata` feeds metadata-driven hooks exactly
+like contract metadata.
+
+**Returns:** Builder with `handle(fn)` returning
+`(req: Request) => Promise<Response>`.
+
+```typescript
+// app/api/liveblocks-auth/route.ts
+import { getServer } from "@/server";
+
+let roomAuth: ((req: Request) => Promise<Response>) | undefined;
+
+export async function POST(req: Request) {
+  roomAuth ??= (await getServer())
+    .rawRoute({
+      name: "collab.roomAuth",
+      method: "POST",
+      path: "/api/liveblocks-auth",
+      metadata: { rateLimit: { max: 300, windowSec: 60, scope: "user" } },
+    })
+    .handle(async ({ req, ctx }) => {
+      const body = await req.text();
+      return { status: 200, body: { token: "..." } };
+    });
+
+  return roomAuth(req);
+}
+```
+
+The webhook, payment webhook, schedule, and outbox drain route factories run
+through this pipeline automatically when the `server` they receive exposes
+`rawRoute(...)`; their `pipeline` option supplies the route identity and
+metadata.
+
 #### `server.createContextFromNext()`
 
 Creates a context object from Next.js Server Components by automatically extracting headers and cookies. This allows you to call use cases directly from React Server Components without going through API routes.
@@ -319,11 +370,14 @@ Creates a context object from Next.js Server Components by automatically extract
 
 ```typescript
 // app/my-page/page.tsx
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { getTodoUseCase } from "@/features/todos/use-cases/get-todo";
 
+export const dynamic = "force-dynamic";
+
 export default async function MyPage() {
   // Create context from Next.js headers and cookies
+  const server = await getServer();
   const ctx = await server.createContextFromNext();
   
   // Call use case directly
@@ -365,9 +419,11 @@ background work:
 ```typescript
 // server/schedules.ts
 import { createServiceActor } from "@beignet/core/ports";
-import { server } from "./index";
+import { getServer } from "./index";
 
 export async function createScheduleContext() {
+  const server = await getServer();
+
   return server.createServiceContext({
     actor: createServiceActor("beignet-schedule"),
   });
@@ -427,7 +483,7 @@ export const GET = server
 Hooks can be added at the server level:
 
 ```typescript
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import { createLoggingHooks } from "@beignet/core/server";
 
 const logging = createLoggingHooks({
@@ -435,18 +491,20 @@ const logging = createLoggingHooks({
   requestIdHeader: "x-request-id",
 });
 
-export const server = await createNextServer({
-  ports: {},
-  hooks: [logging],
-  context: async () => ({}),
-  mapUnhandledError: () => ({
-    status: 500,
-    body: {
-      code: "INTERNAL_SERVER_ERROR",
-      message: "Internal server error",
-    },
+export const getServer = createNextServerLoader(() =>
+  createNextServer({
+    ports: {},
+    hooks: [logging],
+    context: async () => ({}),
+    mapUnhandledError: () => ({
+      status: 500,
+      body: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Internal server error",
+      },
+    }),
   }),
-});
+);
 ```
 
 ## OpenAPI documentation
@@ -459,20 +517,20 @@ docs; request-origin inference is available only when you opt in.
 // app/api/openapi/route.ts
 import { createOpenAPIHandler } from "@beignet/next";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { contracts } from "@/server/routes";
 
-export const GET = createOpenAPIHandler(server.contracts, {
+export const GET = createOpenAPIHandler(contracts, {
   title: "My API",
   version: "1.0.0",
   servers: [{ url: env.APP_URL }],
 });
 ```
 
-`server.contracts` is populated from contracts registered through
-`createNextServer({ routes })`. If you export per-file Next handlers with
-`server.route(contract).handle(...)`, keep an explicit contract list or exported
-route registry for OpenAPI because those route files are not imported by the
-server automatically.
+Export `contracts = contractsFromRoutes(routes)` from `server/routes.ts` so the
+OpenAPI route can stay static and avoid booting providers during Next builds.
+If you export per-file Next handlers with `server.route(contract).handle(...)`,
+keep an explicit contract list because those route files are not imported by
+the server automatically.
 
 You can also serve Swagger UI without writing the HTML route by hand:
 
@@ -495,11 +553,14 @@ objects, private objects, invalid keys, and paths outside `basePath` to 404.
 ```typescript
 // app/storage/[...key]/route.ts
 import { createStorageRoute } from "@beignet/next";
-import { server } from "@/server";
+import { getServer } from "@/server";
 
-export const { GET, HEAD } = createStorageRoute(server.ports.storage, {
-  basePath: "/storage",
-});
+export const { GET, HEAD } = createStorageRoute(
+  async () => (await getServer()).ports.storage,
+  {
+    basePath: "/storage",
+  },
+);
 ```
 
 Served responses preserve object `Content-Type`, `Cache-Control`,
@@ -521,16 +582,18 @@ import { resolveProviderInstrumentationPort } from "@beignet/core/providers";
 import { createUploadRouter } from "@beignet/core/uploads";
 import { createUploadRoute } from "@beignet/next";
 import { postUploads } from "@/features/posts/uploads";
-import { server } from "@/server";
+import { getServer } from "@/server";
 
-const uploadRouter = createUploadRouter({
-  uploads: postUploads,
-  ctx: () => server.createContextFromNext(),
-  storage: server.ports.storage,
-  instrumentation: resolveProviderInstrumentationPort(server.ports),
-});
+export const { POST } = createUploadRoute(async () => {
+  const server = await getServer();
 
-export const { POST } = createUploadRoute(uploadRouter);
+  return createUploadRouter({
+    uploads: postUploads,
+    ctx: () => server.createContextFromNext(),
+    storage: server.ports.storage,
+    instrumentation: resolveProviderInstrumentationPort(server.ports),
+  });
+});
 ```
 
 The `action` segment must be `prepare`, `upload`, or `complete`.
@@ -539,15 +602,26 @@ The `action` segment must be `prepare`, `upload`, or `complete`.
 
 Use `createPaymentWebhookRoute(...)` for billing flows backed by
 `ctx.ports.payments`. Use `createWebhookRoute(...)` for generic inbound
-webhooks backed by a `defineWebhook(...)` catalog and a provider verifier. Both
-helpers preserve the raw request body before app code runs.
+webhooks backed by a `defineWebhook(...)` catalog and a provider verifier.
+The `server` option accepts any object exposing `createRequestContext` — a
+`NextServer`, a core `ServerInstance`, or a test fake — so
+`server: getServer` keeps working unchanged.
+
+When the server also exposes `rawRoute(...)` — real Beignet servers do — the
+route runs inside the full hooks pipeline: rate limiting, CORS, logging,
+error reporting, and instrumentation apply, the request appears in devtools,
+and the `pipeline` option supplies the route identity and metadata for
+metadata-driven hooks. The raw body stays unconsumed until the route reads
+it, so signature verification still sees the exact bytes. Minimal test fakes
+without `rawRoute` keep the direct flow: raw body first, then app context
+through `server.createRequestContext(...)`.
 
 ```typescript
 // app/api/webhooks/github/route.ts
 import { githubWebhook } from "@/features/integrations/webhooks";
 import { handleGitHubWebhookUseCase } from "@/features/integrations/use-cases";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { createWebhookRoute } from "@beignet/next";
 import { createGitHubWebhookVerifier } from "@beignet/provider-webhooks-github";
 
@@ -558,7 +632,7 @@ const githubWebhookVerifier = createGitHubWebhookVerifier({
 });
 
 export const { POST } = createWebhookRoute({
-  server,
+  server: getServer,
   webhook: githubWebhook,
   verify: ({ input }) => githubWebhookVerifier.verify(input),
   handle: async ({ ctx, event }) => {
@@ -571,9 +645,10 @@ export const { POST } = createWebhookRoute({
 });
 ```
 
-Verification failures return 400 so providers do not treat an invalid signature
-as a fulfilled event. Handler failures return 500 so at-least-once webhook
-providers can retry.
+Body read failures return 400 before context creation runs. Verification
+failures return 400 so providers do not treat an invalid signature as a
+fulfilled event. Context creation failures return 500. Handler failures return
+500 so at-least-once webhook providers can retry.
 
 Use provider verifiers such as `createGitHubWebhookVerifier(...)` from
 `@beignet/provider-webhooks-github` or `createStripeWebhookVerifier(...)` from
@@ -589,23 +664,24 @@ billing flows and the route generated by `beignet make payments`.
 ## Outbox drain routes
 
 Use `createOutboxDrainRoute` to expose durable outbox delivery from a cron or
-scheduled serverless route. The helper requires a bearer secret, drains one
-bounded batch with `@beignet/core/outbox`, records a drain summary into the
-instrumentation port resolved from `ctx.ports` (`ports.instrumentation`, then
-`ports.devtools`), passes request correlation fields to outbox
+scheduled serverless route. The helper requires a bearer secret, builds app
+context from the real request with `server.createRequestContext(...)`, drains
+one bounded batch with `@beignet/core/outbox`, records a drain summary into
+the instrumentation port resolved from `ctx.ports` (`ports.instrumentation`,
+then `ports.devtools`), passes request correlation fields to outbox
 instrumentation, and returns a JSON summary.
 
 ```typescript
 // app/api/cron/outbox/drain/route.ts
 import { createOutboxDrainRoute } from "@beignet/next";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { outboxRegistry } from "@/server/outbox";
 
 export const runtime = "nodejs";
 
 export const { GET, POST } = createOutboxDrainRoute({
-  server,
+  server: getServer,
   registry: outboxRegistry,
   secret: env.CRON_SECRET,
   batchSize: 100,
@@ -631,9 +707,10 @@ serverless apps.
 ## Schedule trigger routes
 
 Use `createScheduleRoute` to trigger one registered schedule from a cron or
-scheduled serverless route. The helper requires a bearer secret, creates app
-context with `server.createContextFromNext()`, runs the schedule with the
-inline runner from `@beignet/core/schedules`, and records `schedule` events
+scheduled serverless route. The helper requires a bearer secret, builds app
+context from the real request with `server.createRequestContext(...)`, runs
+the schedule with the inline runner from `@beignet/core/schedules`, and
+records `schedule` events
 through the instrumentation port resolved from `ctx.ports`
 (`ports.instrumentation`, then `ports.devtools`) with the request's
 correlation fields.
@@ -642,13 +719,13 @@ correlation fields.
 // app/api/cron/digests/daily-digest/route.ts
 import { createScheduleRoute } from "@beignet/next";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { schedules } from "@/server/schedules";
 
 export const runtime = "nodejs";
 
 export const { GET, POST } = createScheduleRoute({
-  server,
+  server: getServer,
   schedules,
   schedule: "digests.send-daily",
   secret: env.CRON_SECRET,
@@ -667,6 +744,62 @@ through `ctx.ports.logger` and return a 500 so schedule providers can retry.
 `source` defaults to `"next-cron-route"` and is recorded on run metadata and
 devtools events.
 
+## Testing route files
+
+The webhook, payment webhook, schedule, and outbox drain route factories build
+app context from the incoming request, not from `next/headers`, so route
+modules execute under `bun test` with a plain `Request`. Import the route
+module directly and call the exported handler:
+
+```typescript
+// app/api/webhooks/github/route.test.ts
+import { expect, it } from "bun:test";
+import { POST } from "./route";
+
+it("rejects unsigned webhook deliveries", async () => {
+  const response = await POST(
+    new Request("http://localhost/api/webhooks/github", {
+      method: "POST",
+      body: JSON.stringify({ action: "opened" }),
+    }),
+  );
+
+  expect(response.status).toBe(400);
+});
+```
+
+To test a route factory against controlled context without booting the real
+server, pass any object exposing `createRequestContext` as the `server`
+option (`NextRouteServer<Ctx>`):
+
+```typescript
+import { expect, it } from "bun:test";
+import { createScheduleRoute } from "@beignet/next";
+import { schedules } from "@/server/schedules";
+
+it("triggers the daily digest schedule", async () => {
+  const { POST } = createScheduleRoute({
+    schedules,
+    schedule: "digests.send-daily",
+    secret: "test-secret",
+    server: {
+      async createRequestContext() {
+        return createTestScheduleContext();
+      },
+    },
+  });
+
+  const response = await POST(
+    new Request("http://localhost/api/cron/digests/daily-digest", {
+      method: "POST",
+      headers: { authorization: "Bearer test-secret" },
+    }),
+  );
+
+  expect(response.status).toBe(200);
+});
+```
+
 ## Client creation
 
 Use `createClient` from `@beignet/core/client` for modules under `client/` or
@@ -708,7 +841,7 @@ Beignet supports the normal App Router split:
 - Server Components can call use cases directly with `server.createContextFromNext()`.
 - Server Components can prefetch contract queries and hydrate Client Components with TanStack Query.
 - Client Components use `createClient()` plus React Query options for interactive server state.
-- Route handlers stay thin and expose `server.api` or focused helpers such as OpenAPI, uploads, storage, devtools, and outbox drains.
+- Route handlers stay thin and use `createApiRoute(getServer)` or focused helpers such as OpenAPI, uploads, storage, devtools, and outbox drains.
 
 ### Server Component use-case calls
 
@@ -717,9 +850,11 @@ browser cache for the result:
 
 ```typescript
 // app/posts/[slug]/page.tsx
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { getPostUseCase } from "@/features/posts/use-cases/get-post";
 
+export const dynamic = "force-dynamic";
+
 type PageProps = {
   params: Promise<{
     slug: string;
@@ -728,6 +863,7 @@ type PageProps = {
 
 export default async function Page({ params }: PageProps) {
   const { slug } = await params;
+  const server = await getServer();
   const ctx = await server.createContextFromNext();
   const post = await getPostUseCase.run({
     ctx,
@@ -783,33 +919,35 @@ handlers. Await them before building contract path or query params.
 Providers are service adapters that implement ports (database, cache, logger, etc.):
 
 ```typescript
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import { createDrizzleSqliteProvider } from "@beignet/provider-db-drizzle/sqlite";
 import { loggerPinoProvider } from "@beignet/provider-logger-pino";
 import * as schema from "@/db/schema";
 
 const drizzleSqliteProvider = createDrizzleSqliteProvider({ schema });
 
-export const server = await createNextServer({
-  ports: {},
-  providers: [
-    drizzleSqliteProvider,
-    loggerPinoProvider,
-  ],
-  providerEnv: process.env,
-  context: async ({ ports }) => ({
-    // Access providers via ports
-    db: ports.db,
-    logger: ports.logger,
-  }),
-  mapUnhandledError: () => ({
-    status: 500,
-    body: {
-      code: "INTERNAL_SERVER_ERROR",
-      message: "Internal server error",
-    },
+export const getServer = createNextServerLoader(() =>
+  createNextServer({
+    ports: {},
+    providers: [
+      drizzleSqliteProvider,
+      loggerPinoProvider,
+    ],
+    providerEnv: process.env,
+    context: async ({ ports }) => ({
+      // Access providers via ports
+      db: ports.db,
+      logger: ports.logger,
+    }),
+    mapUnhandledError: () => ({
+      status: 500,
+      body: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Internal server error",
+      },
+    }),
   }),
-});
+);
 ```
 
 ## Error handling
@@ -817,20 +955,24 @@ export const server = await createNextServer({
 ### Global error handler
 
 ```typescript
-export const server = await createNextServer({
-  ports: {},
-  context: async () => ({}),
-  mapUnhandledError: ({ err }) => {
-    console.error("Unhandled error:", err);
-    return {
-      status: 500,
-      body: {
-        code: "INTERNAL_SERVER_ERROR",
-        message: "Internal server error",
-      },
-    };
-  },
-});
+import { createNextServer, createNextServerLoader } from "@beignet/next";
+
+export const getServer = createNextServerLoader(() =>
+  createNextServer({
+    ports: {},
+    context: async () => ({}),
+    mapUnhandledError: ({ err }) => {
+      console.error("Unhandled error:", err);
+      return {
+        status: 500,
+        body: {
+          code: "INTERNAL_SERVER_ERROR",
+          message: "Internal server error",
+        },
+      };
+    },
+  }),
+);
 ```
 
 `mapUnhandledError` response bodies are sent to clients. Use `onCaughtError`
@@ -875,9 +1017,9 @@ Creates a Next.js route handler that returns an OpenAPI 3.1 JSON document. Requi
 Pass `servers` for deployed docs. If `servers` is omitted, no OpenAPI
 `servers` entry is generated unless `inferServersFromRequest: true` is set.
 
-When you use central route registration, prefer `server.contracts` or
-`contractsFromRoutes(routes)` so OpenAPI is generated from the same route list
-used by the runtime.
+When you use central route registration, export `contractsFromRoutes(routes)`
+from `server/routes.ts` so OpenAPI is generated from the same route list used
+by the runtime without booting providers during route-module import.
 
 ### `createSwaggerUIHandler(options?): (req: Request) => Response`
 
@@ -885,17 +1027,20 @@ Creates a Next.js route handler that serves Swagger UI for an OpenAPI endpoint.
 
 ### `createWebhookRoute(options): { POST }`
 
-Creates a generic Next.js webhook route. The route reads the raw body, verifies
-the event through a webhook definition or context-aware verifier, validates the
-matching event payload schema, and delegates the event to your app-owned
-handler.
+Creates a generic Next.js webhook route. The route reads the raw body, builds
+app context from the real request with `server.createRequestContext(...)`,
+verifies the event through a webhook definition or context-aware verifier,
+validates the matching event payload schema, and delegates the event to your
+app-owned handler.
 
 ### `createPaymentWebhookRoute(options): { POST }`
 
-Creates a Next.js payment webhook route. The route reads the raw body, verifies
-the provider signature through `ctx.ports.payments.verifyWebhook(...)`, and
-delegates the normalized event to your app-owned handler. Prefer
-`createWebhookRoute(...)` for new non-payment webhook integrations.
+Creates a Next.js payment webhook route. The route reads the raw body, builds
+app context from the real request with `server.createRequestContext(...)`,
+verifies the provider signature through
+`ctx.ports.payments.verifyWebhook(...)`, and delegates the normalized event to
+your app-owned handler. Prefer `createWebhookRoute(...)` for new non-payment
+webhook integrations.
 
 ### `toRequestLike(req: Request): HttpRequestLike`
 
@@ -995,66 +1140,66 @@ export const contracts = contractsFromRoutes(routes);
 
 ```typescript
 // server/index.ts
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import type { AppContext } from "@/app-context";
 import { routes } from "@/server/routes";
 
-export const server = await createNextServer<AppContext>({
-  ports: {},
-  routes,
-  context: async () => ({ todos: [] }),
-  mapUnhandledError: () => ({
-    status: 500,
-    body: {
-      code: "INTERNAL_SERVER_ERROR",
-      message: "Internal server error",
-    },
+export const getServer = createNextServerLoader(() =>
+  createNextServer<AppContext>({
+    ports: {},
+    routes,
+    context: async () => ({ todos: [] }),
+    mapUnhandledError: () => ({
+      status: 500,
+      body: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Internal server error",
+      },
+    }),
   }),
-});
+);
 ```
 
 ```typescript
 // app/api/[[...path]]/route.ts
-import { server } from "@/server";
-
-export const DELETE = server.api;
-export const GET = server.api;
-export const HEAD = server.api;
-export const OPTIONS = server.api;
-export const PATCH = server.api;
-export const POST = server.api;
-export const PUT = server.api;
+import { createApiRoute } from "@beignet/next";
+import { getServer } from "@/server";
+
+export const { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT } =
+  createApiRoute(getServer);
 ```
 
 ### With authentication
 
 ```typescript
 // server/index.ts
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import { AuthUnauthorizedError } from "@beignet/core/ports";
 import { getTodo } from "@/features/todos/contracts";
 
-export const server = await createNextServer({
-  ports: {},
-  context: async ({ req }) => {
-    const user = await getUserFromRequest(req);
+export const getServer = createNextServerLoader(() =>
+  createNextServer({
+    ports: {},
+    context: async ({ req }) => {
+      const user = await getUserFromRequest(req);
 
-    if (!user) {
-      throw new AuthUnauthorizedError();
-    }
+      if (!user) {
+        throw new AuthUnauthorizedError();
+      }
 
-    return { user };
-  },
-  mapUnhandledError: () => {
-    return {
-      status: 500,
-      body: {
-        code: "INTERNAL_SERVER_ERROR",
-        message: "Internal server error",
-      },
-    };
-  },
-});
+      return { user };
+    },
+    mapUnhandledError: () => {
+      return {
+        status: 500,
+        body: {
+          code: "INTERNAL_SERVER_ERROR",
+          message: "Internal server error",
+        },
+      };
+    },
+  }),
+);
 ```
 
 ### Server component usage
@@ -1063,11 +1208,14 @@ You can call use cases directly from React Server Components using `createContex
 
 ```typescript
 // app/todos/page.tsx
-import { server } from "@/server";
+import { getServer } from "@/server";
 import { listTodosUseCase } from "@/features/todos/use-cases/list-todos";
 
+export const dynamic = "force-dynamic";
+
 export default async function TodosPage() {
   // Create context from Next.js runtime
+  const server = await getServer();
   const ctx = await server.createContextFromNext();
   
   // Call use case directly - no API route needed!