oRPC Contract-First Development

Intent

• Keep contract as single source of truth in web/contract/*.

• Default query usage: call-site useQuery(consoleQuery|marketplaceQuery.xxx.queryOptions(...)) when endpoint behavior maps 1:1 to the contract.

• Keep abstractions minimal and preserve TypeScript inference.

Minimal Structure

web/contract/

├── base.ts

├── router.ts

├── marketplace.ts

└── console/

    ├── billing.ts

    └── ...other domains

web/service/client.ts

Core Workflow

• Define contract in web/contract/console/{domain}.ts or web/contract/marketplace.ts

• Use base.route({...}).output(type<...>()) as baseline.

• Add .input(type<...>()) only when request has params/query/body.

• For GET without input, omit .input(...) (do not use .input(type<unknown>())).

• Register contract in web/contract/router.ts

• Import directly from domain files and nest by API prefix.

• Consume from UI call sites via oRPC query utils.

import { useQuery } from '@tanstack/react-query'

import { consoleQuery } from '@/service/client'

const invoiceQuery = useQuery(consoleQuery.billing.invoices.queryOptions({

  staleTime: 5 * 60 * 1000,

  throwOnError: true,

  select: invoice => invoice.url,

}))

Query Usage Decision Rule

• Default: call site directly uses *.queryOptions(...).

• If 3+ call sites share the same extra options (for example retry: false), extract a small queryOptions helper, not a use-* passthrough hook.

• Create web/service/use-{domain}.ts only for orchestration:

• Combine multiple queries/mutations.

• Share domain-level derived state or invalidation helpers.

const invoicesBaseQueryOptions = () =>

  consoleQuery.billing.invoices.queryOptions({ retry: false })

const invoiceQuery = useQuery({

  ...invoicesBaseQueryOptions(),

  throwOnError: true,

})

Mutation Usage Decision Rule

• Default: call mutation helpers from consoleQuery / marketplaceQuery, for example useMutation(consoleQuery.billing.bindPartnerStack.mutationOptions(...)).

• If mutation flow is heavily custom, use oRPC clients as mutationFn (for example consoleClient.xxx / marketplaceClient.xxx), instead of generic handwritten non-oRPC mutation logic.

Key API Guide ( .key vs .queryKey vs .mutationKey )

• .key(...):

• Use for partial matching operations (recommended for invalidation/refetch/cancel patterns).

• Example: queryClient.invalidateQueries({ queryKey: consoleQuery.billing.key() })

• .queryKey(...):

• Use for a specific query's full key (exact query identity / direct cache addressing).

• .mutationKey(...):

• Use for a specific mutation's full key.

• Typical use cases: mutation defaults registration, mutation-status filtering (useIsMutating, queryClient.isMutating), or explicit devtools grouping.

Anti-Patterns

• Do not wrap useQuery with options?: Partial<UseQueryOptions>.

• Do not split local queryKey/queryFn when oRPC queryOptions already exists and fits the use case.

• Do not create thin use-* passthrough hooks for a single endpoint.

• Reason: these patterns can degrade inference (data may become unknown, especially around throwOnError/select) and add unnecessary indirection.

Contract Rules

• Input structure: Always use { params, query?, body? } format

• No-input GET: Omit .input(...); do not use .input(type<unknown>())

• Path params: Use {paramName} in path, match in params object

• Router nesting: Group by API prefix (e.g., /billing/* -> billing: {})

• No barrel files: Import directly from specific files

• Types: Import from @/types/, use type<T>() helper

• Mutations: Prefer mutationOptions; use explicit mutationKey mainly for defaults/filtering/devtools

Type Export

export type ConsoleInputs = InferContractRouterInputs<typeof consoleRouterContract>