@contract-kit/server

Framework-agnostic HTTP server runtime for Contract Kit.

Use this package when you are building a server adapter or running Contract Kit outside a framework-specific package. For Next.js apps, prefer @contract-kit/next.

Install

bun add @contract-kit/server @contract-kit/core @contract-kit/ports

Minimal setup

import { createServer, defineRoutes } from "@contract-kit/server";
import { definePorts } from "@contract-kit/ports";
import { getTodo } from "@/contracts/todos";

const ports = definePorts({});

export const server = await createServer({
  ports,
  createContext: ({ ports }) => ({
    requestId: crypto.randomUUID(),
    ports,
  }),
  routes: defineRoutes([
    {
      contract: getTodo,
      handle: async ({ path }) => ({
        status: 200,
        body: { id: path.id, title: "Example", completed: false },
      }),
    },
  ]),
});

createServer(...) returns a framework-agnostic server instance. Framework adapters convert their native request/response objects into Contract Kit's HttpRequestLike and HttpResponse shapes.

Core exports

| Export | Purpose | | --- | --- | | createServer(options) | Create a framework-agnostic Contract Kit server | | defineRoutes(routes) | Preserve route handler inference for route arrays | | createHealthContract(options?) | Define a standard health endpoint contract | | createHealthRoute(contract, handler?) | Create a standard health route | | createOpenAPIContract(options?) | Define a standard OpenAPI endpoint contract | | createRateLimitHooks(options?) | Enforce contract metadata-driven rate limits | | createRequestLoggerHook(options?) | Add request logging around handlers | | HttpRequestLike | Adapter-facing request interface | | HttpResponse | Adapter-facing response shape | | RouteDef | Route registration type | | ServerInstance | Created server instance type |

Request lifecycle

The runtime owns route matching, request parsing, request validation, context creation, hook execution, handler execution, response validation, and error mapping. Route handlers should return { status, body, headers? } or a native Response when the adapter supports it.

Providers

Servers can install Contract Kit providers during startup:

export const server = await createServer({
  ports,
  providers: [loggerPinoProvider, redisProvider],
  createContext: ({ ports }) => ({ ports }),
  routes,
});

Provider-installed ports are available to later providers, createContext, hooks, handlers, use cases, and server.ports.

Error handling

Declared AppError instances are mapped to Contract Kit's standard error envelope. Unknown failures are passed to mapUnhandledError when provided. Use onCaughtError hooks for logging, tracing, and metrics without changing response behavior.

Read next

• Docs site server guide: https://contract-kit.dev/server
• Request lifecycle: https://contract-kit.dev/request-lifecycle
• Hooks: https://contract-kit.dev/hooks
• Providers: https://contract-kit.dev/providers

License

MIT