devjarus/shared-contracts

Shared Contracts

When to Apply

• Project has both frontend and backend in the same repo
• API endpoints are consumed by frontend components
• Multiple services share data types
• Planner identifies cross-domain data dependencies

---

Priority Rules

CRITICAL

• SHR-01: Define shared types/schemas in ONE location — both frontend and backend import from it
• SHR-02: API request/response shapes are defined as Zod schemas (or equivalent) — used for both runtime validation and TypeScript type inference

HIGH

• SHR-03: Shared package lives at a known path (e.g., packages/shared/, lib/shared/, or src/types/api.ts in a monorepo)
• SHR-04: Changes to shared contracts require updating BOTH consumers — never change a contract in isolation
• SHR-05: API error response format is standardized and shared (not reinvented per endpoint)

MEDIUM

• SHR-06: Use Zod z.infer<typeof schema> for TypeScript types — single source of truth for type AND validation
• SHR-07: For REST APIs, consider OpenAPI spec as the contract — generate client types from it
• SHR-08: For tRPC/GraphQL, the framework IS the contract — lean on it instead of manual types

---

Patterns

Pattern 1: Shared Zod Schemas (monorepo or full-stack app)

Define the schema once in a shared location. Both the API route and the frontend import from it — the schema drives runtime validation on the server and form validation + TypeScript types on the client.

// packages/shared/src/schemas/user.ts
import { z } from "zod"

export const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  role: z.enum(["admin", "member", "viewer"]),
})

export type CreateUserInput = z.infer<typeof CreateUserSchema>

// backend: apps/api/src/routes/users.ts
import { CreateUserSchema } from "@myapp/shared/schemas/user"

app.post("/users", async (req, res) => {
  const result = CreateUserSchema.safeParse(req.body)
  if (!result.success) {
    return res.status(400).json({ error: result.error.flatten() })
  }
  // result.data is fully typed as CreateUserInput
  await createUser(result.data)
  res.status(201).json({ ok: true })
})

// frontend: apps/web/src/features/users/CreateUserForm.tsx
import { CreateUserSchema, type CreateUserInput } from "@myapp/shared/schemas/user"

function CreateUserForm() {
  const { register, handleSubmit } = useForm<CreateUserInput>({
    resolver: zodResolver(CreateUserSchema), // same schema, client-side validation
  })
  // ...
}

Pattern 2: OpenAPI Contract-First

Define the OpenAPI spec as the single source of truth. Generate server stubs and client types from it so both sides are always in sync — no manual type duplication.

# openapi.yaml
paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserInput"
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

# generate server types
npx openapi-typescript openapi.yaml --output src/types/api.d.ts

# generate client (e.g., with orval or openapi-fetch)
npx orval --input openapi.yaml --output src/api/client.ts

Both the backend route handler and the frontend API client are typed from the same spec. A breaking change to the spec surfaces as a TypeScript error in both.

Pattern 3: tRPC (Next.js full-stack)

The router definition IS the contract. The frontend gets a type-safe client automatically — no codegen step, no manual types, no drift possible.

// server/routers/user.ts
export const userRouter = router({
  create: publicProcedure
    .input(
      z.object({
        email: z.string().email(),
        name: z.string().min(1),
      })
    )
    .mutation(async ({ input }) => {
      return db.user.create({ data: input })
    }),
})

// frontend component
const { mutate } = trpc.user.create.useMutation()
// input is fully typed — TypeScript errors if shape drifts
mutate({ email: "[email protected]", name: "Alice" })

---

Anti-Patterns

| Anti-pattern | Why it's harmful | |---|---| | Duplicating types in frontend/ and backend/ separately | The two copies drift immediately. Renaming a field on one side silently breaks the other. | | Using any at API boundaries | Defeats TypeScript entirely. Runtime shape mismatches become silent bugs. | | Changing backend response without updating the frontend consumer | The contract is broken the moment the PR merges. Only caught at runtime or in E2E tests. | | TypeScript types only — no runtime validation | Types disappear at compile time. An unexpected server payload or a bad environment variable causes a runtime crash with no useful error. |