@beignet/next 0.0.25 → 0.0.27

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,23 +294,26 @@ 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.createContextFromNext()`
@@ -319,11 +324,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 +373,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 +437,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 +445,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 +471,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 +507,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 +536,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`.
@@ -540,14 +557,19 @@ 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.
+helpers read the raw request body first, then build app context from the real
+request with `server.createRequestContext(...)`, so signature verification
+never races the context factory over one body stream and trace headers
+propagate into context creation. The `server` option accepts any object
+exposing `createRequestContext` — a `NextServer`, a core `ServerInstance`, or
+a test fake — so `server: getServer` keeps working unchanged.
 
 ```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 +580,7 @@ const githubWebhookVerifier = createGitHubWebhookVerifier({
 });
 
 export const { POST } = createWebhookRoute({
-  server,
+  server: getServer,
   webhook: githubWebhook,
   verify: ({ input }) => githubWebhookVerifier.verify(input),
   handle: async ({ ctx, event }) => {
@@ -571,9 +593,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 +612,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 +655,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 +667,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 +692,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 +789,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 +798,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 +811,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 +867,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 +903,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 +965,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 +975,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 +1088,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 +1156,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!