Next.js: add one endpoint
Add ContractSpec to an existing Next.js App Router project by wiring a single operation end-to-end with validation and types.
What you'll build
One OperationSpec with SchemaModel validation.
A registry wiring the operation to its handler.
A Next.js route handler that exposes the operation.
1) Install core packages
bash
bun add -D contractspec
bun add @lssm-tech/lib.contracts-spec @lssm-tech/lib.contracts-runtime-server-rest @lssm-tech/lib.schemaExpected output: added 3 packages and a lockfile update.
2) Define the operation spec
Create src/contracts/healthcheck.operation.ts:
typescript
import { defineQuery } from "@lssm-tech/lib.contracts-spec/operations";
import { SchemaModel, ScalarTypeEnum } from "@lssm-tech/lib.schema";
const HealthcheckOutput = new SchemaModel({
name: "HealthcheckOutput",
fields: {
status: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
checkedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
},
});
export const HealthcheckQuery = defineQuery({
meta: {
key: "healthcheck.get",
version: "1.0.0",
description: "Return service health status",
owners: ["@platform.core"],
tags: ["health", "observability"],
},
io: {
input: null,
output: HealthcheckOutput,
},
policy: {
auth: "public",
},
transport: {
rest: { method: "GET" },
gql: { field: "healthcheck_get" },
mcp: { toolName: "healthcheck_get-v1" },
},
});3) Register the operation
Create src/contracts/registry.ts:
typescript
import {
OperationSpecRegistry,
installOp,
} from "@lssm-tech/lib.contracts-spec/operations";
import { HealthcheckQuery } from "./healthcheck.operation";
export const registry = new OperationSpecRegistry();
installOp(registry, HealthcheckQuery, async () => ({
status: "ok",
checkedAt: new Date().toISOString(),
}));4) Add the Next.js handler
Create app/api/ops/[...route]/route.ts:
typescript
import { makeNextAppHandler } from "@lssm-tech/lib.contracts-runtime-server-rest/rest-next-app";
import { registry } from "@/contracts/registry";
const handler = makeNextAppHandler(registry, async () => ({
actor: "public",
tenantId: "public",
}));
export { handler as GET, handler as POST };Expected output: the route responds at /api/ops/healthcheck.get.
5) Validate the spec
bash
contractspec validate src/contracts/healthcheck.operation.tsExpected output: Validation passed.
Example package
Use @lssm-tech/example.lifecycle-dashboard as a lightweight Next.js snippet reference.
bash
# Inspect the example docs
contractspec examples show lifecycle-dashboard
# Validate all example manifests in this repo
contractspec examples validate --repo-root .Want real product evidence behind endpoint changes?
Studio correlates meetings, support, analytics, and code signals before compiling endpoint decisions into spec diffs.
See what Studio adds