Contract-First

Introduction

The contract-first approach is a powerful methodology for API development. It offers several key advantages:

Enables parallel development of client and server components
Facilitates clear API definition before implementation
Simplifies publishing TypeScript clients to npm registry
Reduces type conflicts between client and server

Installation

npm i @orpc/contract @orpc/server @orpc/client

Define Your Contract

Start by defining your API contract:

import { oc, type InferContractRouterInputs, type InferContractRouterOutputs } from '@orpc/contract'
import { oz } from '@orpc/zod'
import { z } from 'zod'
 
export const contract = oc.router({
    getting: oc
    .input(
      z.object({
        name: z.string(),
      }),
    )
    .output(
      z.object({
        message: z.string(),
      }),
    ),
 
  post: oc.prefix('/posts').router({
    find: oc
      .route({
        path: '/{id}',
        method: 'GET',
      })
      .input(
        z.object({
          id: z.string(),
        }),
      )
      .output(
        z.object({
          id: z.string(),
          title: z.string(),
          description: z.string(),
        }),
      ),
 
    create: oc
      .input(
        z.object({
          title: z.string(),
          description: z.string(),
          thumb: oz.file().type('image/*'),
        }),
      )
      .output(
        z.object({
          id: z.string(),
          title: z.string(),
          description: z.string(),
        }),
      ),
  }),
})
 
export type Inputs = InferContractRouterInputs<typeof contract>
export type Outputs = InferContractRouterOutputs<typeof contract>

Implement Your Server

With your contract defined, implement the server logic:

import { os, ORPCError } from '@orpc/server'
import { contract } from 'examples/contract'
 
export const pub /** public access */ = os.contract(contract) // Ensure every implement must be match contract
export const authed /** require authed */ = os
  .use((input, context, meta) => /** put auth logic here */ meta.next({}))
  .contract(contract)
 
export const router = pub.router({
  getting: pub.getting.func((input, context, meta) => {
    return {
      message: `Hello, ${input.name}!`,
    }
  }),
 
  post: {
    find: pub.post.find
      .func((input, context, meta) => {
        return {
          id: 'example',
          title: 'example',
          description: 'example',
        }
      }),
 
    create: authed.post.create.func((input, context, meta) => {
      return {
        id: 'example',
        title: input.title,
        description: input.description,
      }
    }),
  },
})

That's it! The contract definition and implementation are now completely separated, allowing for clean, maintainable code.

Client Usage

Create a fully typed client using just the contract definition:

import { createORPCClient, ORPCError } from '@orpc/client'
import type { contract } from 'examples/contract'
 
const client = createORPCClient<typeof contract /* or server router */>({
  baseURL: 'http://localhost:3000/prefix',
  // fetch: optional override for the default fetch function
  // headers: provide additional headers
})
 
//  File upload out of the box
const output = await client.post.create({
  title: 'My Amazing Title',
  description: 'This is a detailed description of my content',
  thumb: (document.getElementById('thumb') as HTMLInputElement).files[0]!,
})
 
client.post.create
find
 
 
 
 
// typesafe and completion out of box

The client is type-safe and can be used in any JavaScript environment.

Benefits of Contract-First Development

Type Safety: Ensures consistency between client and server
Clear API Documentation: The contract serves as living documentation
Parallel Development: Teams can work independently on client and server
Easy Testing: Mock implementations can be created from the contract
Version Control: API changes are tracked through contract changes

By following this approach, you create a robust foundation for your API development process.