@zvk/server-kit

Framework-agnostic HTTP response, pagination, route handler, validation, and test helpers for ZVK applications.

Public imports:

• @zvk/server-kit
• @zvk/server-kit/actions
• @zvk/server-kit/env
• @zvk/server-kit/http
• @zvk/server-kit/logger
• @zvk/server-kit/pagination
• @zvk/server-kit/routes
• @zvk/server-kit/validation
• @zvk/server-kit/test-utils
• @zvk/server-kit/hono
• @zvk/server-kit/hono-openapi
• @zvk/server-kit/hono-test-utils

See ../../docs/package-boundary-matrix.md for the package-family runtime boundary matrix covering browser-safe, server-only, adapter, Node-only, and test-only subpaths.

@zvk/server-kit/actions maps shared contract results and schema-validated action input into flattened server action response envelopes. It intentionally exposes the flattened action result shape plus bridge helpers such as actionResultFromResult and actionResultFromContractActionResult. Use parseActionInput when app code owns the schema, invalid-copy, and downstream action behavior but should not recreate validation-to-action-error mapping. Use parseZodActionInput when the app owns a Zod-like schema and should not compose schema adapters locally. @zvk/server-kit/env creates configured placeholder policies for shared production-env checks. Apps still own the actual env schema and placeholder values, while the package handles explicit-production detection, missing value classification, placeholder rejection, local-default issue collection, and small helpers for normalizing NODE_ENV and attaching optional deployment env. @zvk/server-kit/logger emits dependency-free JSON log lines with recursive sensitive-key redaction.

Hono adapters

@zvk/server-kit/hono provides framework-adapter behavior for Hono apps:

• createHonoRouteHandler for binding app-owned route logic to a Hono Context.
• readHonoRequestParts for normalized { params, query, body } extraction.
• jsonResponse and createHonoErrorMapper for stable response envelopes.
• registerHonoHealthRoutes for a shared health endpoint convention.

@zvk/server-kit/hono-openapi provides OpenAPI-oriented helpers without app-owned routing logic:

• createStandardOpenApiResponses
• createOpenApiJsonRoute
• assertOpenApiRouteContract
• registerOpenApiDocs

@zvk/server-kit/hono-test-utils includes deterministic test primitives for Hono route-handler tests, so apps do not reimplement request/response doubles.

Dependency policy

• Keep @zvk/server-kit root imports framework-neutral.
• Treat hono as an adapter peer dependency for @zvk/server-kit/hono.
• Treat @hono/zod-openapi as optional for @zvk/server-kit/hono-openapi.
• @zvk/server-kit subpath adapters should not make Next.js, DB, auth, or UI assumptions.

App-owned responsibilities

Keep the following in the app layer:

• Route definitions and mount paths.
• Auth/session/project policy and authorization outcomes.
• Domain schemas, generated-client compatibility constraints, and public API contracts.
• User-facing copy, links, and redirect targets.
• Tenant/account/project data ownership decisions.

Migration patterns

Route handling

Before:

import { Hono } from "hono";
import { projectParamsSchema } from "./schema";

const app = new Hono();

app.get("/projects/:id", async (c) => {
  const raw = c.req.param();
  const parsed = projectParamsSchema.safeParse({ id: raw.id });
  if (!parsed.success) {
    return c.json({ error: "invalid route params" }, 400);
  }
  const project = await getProject(parsed.data.id);
  return c.json({ data: project });
});

After:

import { Hono } from "hono";
import { ok } from "@zvk/contracts";
import { createHonoRouteHandler, readHonoRequestParts } from "@zvk/server-kit/hono";

const app = new Hono();

const getProjectRoute = createHonoRouteHandler({
  read: (context) => readHonoRequestParts<{ id: string }, Record<string, never>, undefined>(context),
  run: async ({ params }) => ok(await getProject(params.id)),
});

app.get("/projects/:id", getProjectRoute);

OpenAPI contracts

import { createOpenApiJsonRoute, createStandardOpenApiResponses } from "@zvk/server-kit/hono-openapi";

const route = createOpenApiJsonRoute({
  method: "get",
  path: "/projects/{id}",
  summary: "Fetch a project",
  tags: ["projects"],
  responses: Object.values(createStandardOpenApiResponses({
    successDescription: "Project found",
    errorDescription: "Validation failed",
    notFoundDescription: "Project missing",
  })),
});

// Register `route` with the app-owned OpenAPI router for your Hono stack.

Repo Skill

Use .codex/skills/use-zvk-server-kit/SKILL.md when maintaining this package.

See ../../docs/package-boundary-matrix.md for the browser-safe, server-only, adapter-only, Node-only, and test-only subpaths.