@bfs/contracts

Shared oRPC contracts, Zod schemas, and TypeScript types for the Brite Future Schools platform.

This package is the single source of truth for all API shapes across every repo. It is published privately to GitHub Packages and installed by bfs-api, bfs-web, and bfs-mobile.

What's in here

| Export path | Contents | |---|---| | @bfs/contracts | Everything (re-exports both below) | | @bfs/contracts/schemas | All Zod schemas (inputs, outputs, enums) | | @bfs/contracts/contracts | All oRPC contract definitions + AppContract type |

Architecture

bfs-contracts  ──► published as @bfs/contracts
     ▲                    │
     │         ┌──────────┼──────────┐
     │      bfs-api    bfs-web   bfs-mobile
     │      (server)  (client)  (client)
     │
  oRPC contract-first pattern:
  - Contracts define the shape (input/output Zod schemas)
  - API implements each contract procedure
  - Web/mobile create typed clients from the same contracts

Why a separate package?

Because the three apps live in separate repos and are deployed independently. Without a shared package you would either:

• Duplicate type definitions (gets out of sync immediately), or
• Import from bfs-api directly (creates a runtime dependency)

The contract package is zero runtime for web/mobile — it is only used for TypeScript types and Zod validation at build time.

Installation (in each app repo)

# .npmrc (root of each repo)
@bfs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

# then
pnpm add @bfs/contracts

Local development (without publishing)

Use pnpm link or point to a local path in each repo's package.json:

{
  "dependencies": {
    "@bfs/contracts": "file:../bfs-contracts"
  }
}

Adding a new procedure

1. Add the Zod schema to src/schemas/index.ts
2. Add the contract procedure to the relevant router in src/contracts/index.ts
3. Bump the version: pnpm version patch
4. Push — GitHub Actions publishes automatically

Build

pnpm build      # builds to dist/
pnpm dev        # watch mode
pnpm type-check # TypeScript check without building

Versioning policy

| Change type | Version bump | |---|---| | New procedure added | patch | | Input/output schema changed (non-breaking) | minor | | Breaking schema change | major |

Always update bfs-api first, then bfs-web and bfs-mobile.