Shared Package Guidelines

Scope

This file applies to packages/shared.

Purpose

@repo/shared contains reusable TypeScript and Zod contracts shared by the client and server. Treat it as the source of truth for payloads that cross the network boundary.

Structure

• src/models/*: domain models and reusable schemas.
• src/api.ts: API-related schemas and helpers.
• src/envelope.ts: envelope and response primitives.
• src/index.ts: public package exports.

Rules

• Prefer Zod schemas as the primary definition, then derive types from them.
• Keep this package framework-agnostic and environment-agnostic.
• Avoid adding browser-only or Node-only dependencies here.
• Keep exports intentional. Update barrel exports when adding new models.
• Favor additive changes; if a contract change is breaking, make that explicit in the change summary and update both consumers in the same work.
• Rebuild this package after changing shared contracts before validating consuming apps.

Validation Guidance

• Put schemas here when both frontend and backend should validate the same payload or response shape.
• Keep server-only validation in apps/server and view-only validation in apps/client.

Verification

Validate shared-contract changes from the repo root:

• pnpm --filter @repo/shared build
• pnpm --filter @repo/shared type-check
• pnpm test:client
• pnpm test:server

If a shared contract changes, check both consuming apps before finishing.