oRPC — this repo's API layer
Every API call in this app is an oRPC procedure under webapp/lib/orpc/, served by one Next.js
route handler at webapp/app/api/rpc/[[...rest]]/route.ts (OpenAPIHandler + CORS +
RatelimitHandlerPlugin; the OpenAPI/Scalar plugin is dev-only).
This is not tRPC and there is no Hono server. Do not introduce either.
Load the reference that matches the task
| Task |
Reference |
Write or change a procedure — tier, .route(), input, handler, errors, wiring |
references/procedure-anatomy.md |
A mutation — .actionable(), buildActionContext, cacheInvalidator, the client hook |
references/mutations-and-cache.md |
| Read data — RSC caller, TanStack Query, the typed client, why the contract matters |
references/client-and-server.md |
| Middleware chain, context fields, rate-limit tiers, adding a guard |
references/middleware-and-context.md |
| List endpoints — cursor shape, tiebreaker, when offset is allowed |
references/pagination.md |
| Proving a procedure works — Playwright request tests against the running server |
references/testing-procedures.md |
Depth lives in docs/orpc/ (README, architecture, procedures, schemas, middleware,
client, realtime) — this skill is the summary, those are the manual. Caveat: realtime.md
describes lib/orpc/realtime.ts, absent from webapp/ — streaming is a design here, not code.
The eight rules
- Pick a tier, never build one. Import
publicProcedure, authProcedure,
protectedProcedure, adminProcedure or paidProcedure from webapp/lib/orpc/base.ts. Never
import os from @orpc/server in a feature file.
base.ts and schemas.ts are PROTECTED — READ ONLY; router.ts and index.ts are
PROTECTED — APPEND ONLY. Those banners are line 1 of each file. Feature logic goes in
webapp/lib/orpc/procedures/.
- Identity comes from JWT claims, not from a session round-trip. The auth middleware calls
supabase.auth.getClaims() and hands the handler context.user
({ id, email?, role, plan }). Read context.user; never call auth.getUser() or
auth.getSession() in a new handler.
- Entitlement fails closed.
resolveUserFromClaims defaults plan to 'free'
(webapp/lib/orpc/resolve-user.ts:24). Gate on context.user.plan, or use paidProcedure,
which 403s every 'free' user.
- Zod v4, imported plainly.
import { z } from 'zod' — the package is zod ^4.3.6. Never
zod/v4. Every input is secureObject({...}) from ../schemas, never a bare z.object().
- Throw
Errors.*, never new Error(). webapp/lib/orpc/errors.ts maps each factory to an
HTTP status the client already understands.
- Every mutation gets an
.actionable() server action in webapp/features/{feature}/actions.ts
that busts a cache tag. An HTTP-called mutation cannot invalidate the server cache.
- A procedure reaches the browser client only if it is in the contract.
webapp/lib/orpc/contracts/index.ts is what OpenAPILink is built from. A procedure in
router.ts but not in the contract is server-callable only.
A procedure, whole
// webapp/lib/orpc/procedures/posts.ts
import { protectedProcedure } from '../base'
import { SecureShortText, SecureId, secureObject } from '../schemas'
import { Errors } from '../errors'
export const rename = protectedProcedure
.route({ method: 'POST', path: '/protected/posts/rename' })
.input(secureObject({ id: SecureId, title: SecureShortText.min(1, 'Title is required') }))
.handler(async ({ context, input }) => {
const { data, error } = await context.supabase
.from('posts')
.update({ title: input.title })
.eq('id', input.id)
.eq('user_id', context.user.id) // RLS also enforces this; the filter keeps the 404 honest
.select('id, title')
.single()
if (error) throw Errors.internal(error.message)
if (!data) throw Errors.notFound('Post not found')
return { success: true, post: data }
})
export const postsRouter = { rename }
Then append posts: postsRouter to protectedRouter in procedures/protected.ts, and add the
matching contract entry if the browser needs to call it.
Tiers
| Builder |
Auth |
Rate limit key |
Use for |
publicProcedure |
none |
client IP |
health, public reads |
authProcedure |
none |
client IP, stricter |
sign-in, sign-up, password reset |
protectedProcedure |
required |
user id |
everything a signed-in user does |
paidProcedure |
required, plan !== 'free' |
user id |
writes free users must not reach |
adminProcedure |
required, role === 'admin' |
user id |
admin surfaces |
The chain is built once in base.ts: context init → tracing → Supabase client → rate limit →
Sentry onError → logging → analytics, then the tier's own guards.
Errors
| Factory |
e.code |
Status |
Errors.unauthorized() |
UNAUTHORIZED |
401 |
Errors.forbidden(msg) |
FORBIDDEN |
403 |
Errors.notFound(msg) |
NOT_FOUND |
404 |
Errors.badRequest(msg, { field }) |
BAD_REQUEST |
400 |
Errors.internal(msg) |
INTERNAL_SERVER_ERROR |
500 |
Errors.validation(msg, { field }) |
VALIDATION_ERROR |
app-defined code |
Errors.rateLimited(seconds) |
RATE_LIMITED |
app-defined code |
The last two are codes this app invented (webapp/lib/orpc/errors.ts), not oRPC standard ones —
branch on e.code, never on the status number. A client's 429 comes from the rate-limit plugin.
Mutation, end to end
// webapp/features/posts/actions.ts
'use server'
import { rename as renameProcedure } from '@/lib/orpc/procedures/posts'
import { buildActionContext, cacheInvalidator } from '@/lib/orpc/action-utils'
export const renameAction = renameProcedure.actionable({
context: buildActionContext,
interceptors: [cacheInvalidator('posts')], // generic <T> is the output type; let it infer
})
// webapp/features/posts/hooks/index.ts — 'use client'
const mutation = useMutation({
mutationFn: async (values: RenameValues) => {
const [error, data] = await renameAction(values)
if (error) throw new Error(error.message ?? 'Rename failed')
return data
},
onSuccess: () => router.refresh(),
})
cacheInvalidator calls updateTag() server-side; router.refresh() re-renders the server
components. Never queryClient.invalidateQueries() for a mutation — the server cache is the source
of truth, and updateTag() inside the HTTP handler 500s.
Reading
- Server component:
const caller = await getORPCCaller() then caller.protected.settings.getProfile().
It reads cookies, so it is not safe inside use cache — use getPublicORPCCaller() there.
- Client component:
useQuery(orpc.protected.me.queryOptions()), or await client.protected.me().
Never fetch in a useEffect.
List shapes
{ items, nextCursor, hasMore } for cursor, { items, page, hasMore, totalCount } for offset.
Always name the array items. Cursor is the default; offset only for admin page-jumping.
references/pagination.md has the query and the required index.
1---2name: orpc-fullstack3description: >4 The house oRPC API layer — procedure tiers, secure Zod input, typed errors, the OpenAPI route5 handler, server actions and cache tags, the typed client. Use for "orpc", "add an endpoint",6 "new procedure", "api route", "protectedProcedure", "zod schema", "actionable", "server action",7 "cache tag", "cursor pagination", "rate limit an endpoint", "call this from the client".8 Depth lives under `references/`.9metadata:10 source: https://skillmd.com/skills/dabhiram13/orpc-fullstack11---1213# oRPC — this repo's API layer1415Every API call in this app is an oRPC procedure under `webapp/lib/orpc/`, served by one Next.js16route handler at `webapp/app/api/rpc/[[...rest]]/route.ts` (`OpenAPIHandler` + CORS +17`RatelimitHandlerPlugin`; the OpenAPI/Scalar plugin is dev-only).1819This is not tRPC and there is no Hono server. Do not introduce either.2021## Load the reference that matches the task2223| Task | Reference |24|---|---|25| Write or change a procedure — tier, `.route()`, input, handler, errors, wiring | `references/procedure-anatomy.md` |26| A mutation — `.actionable()`, `buildActionContext`, `cacheInvalidator`, the client hook | `references/mutations-and-cache.md` |27| Read data — RSC caller, TanStack Query, the typed client, why the contract matters | `references/client-and-server.md` |28| Middleware chain, context fields, rate-limit tiers, adding a guard | `references/middleware-and-context.md` |29| List endpoints — cursor shape, tiebreaker, when offset is allowed | `references/pagination.md` |30| Proving a procedure works — Playwright request tests against the running server | `references/testing-procedures.md` |3132Depth lives in `docs/orpc/` (`README`, `architecture`, `procedures`, `schemas`, `middleware`,33`client`, `realtime`) — this skill is the summary, those are the manual. Caveat: `realtime.md`34describes `lib/orpc/realtime.ts`, absent from `webapp/` — streaming is a design here, not code.3536## The eight rules37381. **Pick a tier, never build one.** Import `publicProcedure`, `authProcedure`,39 `protectedProcedure`, `adminProcedure` or `paidProcedure` from `webapp/lib/orpc/base.ts`. Never40 import `os` from `@orpc/server` in a feature file.412. **`base.ts` and `schemas.ts` are `PROTECTED — READ ONLY`; `router.ts` and `index.ts` are42 `PROTECTED — APPEND ONLY`.** Those banners are line 1 of each file. Feature logic goes in43 `webapp/lib/orpc/procedures/`.443. **Identity comes from JWT claims, not from a session round-trip.** The auth middleware calls45 `supabase.auth.getClaims()` and hands the handler `context.user`46 (`{ id, email?, role, plan }`). Read `context.user`; never call `auth.getUser()` or47 `auth.getSession()` in a new handler.484. **Entitlement fails closed.** `resolveUserFromClaims` defaults `plan` to `'free'`49 (`webapp/lib/orpc/resolve-user.ts:24`). Gate on `context.user.plan`, or use `paidProcedure`,50 which 403s every `'free'` user.515. **Zod v4, imported plainly.** `import { z } from 'zod'` — the package is `zod ^4.3.6`. Never52 `zod/v4`. Every input is `secureObject({...})` from `../schemas`, never a bare `z.object()`.536. **Throw `Errors.*`, never `new Error()`.** `webapp/lib/orpc/errors.ts` maps each factory to an54 HTTP status the client already understands.557. **Every mutation gets an `.actionable()` server action** in `webapp/features/{feature}/actions.ts`56 that busts a cache tag. An HTTP-called mutation cannot invalidate the server cache.578. **A procedure reaches the browser client only if it is in the contract.**58 `webapp/lib/orpc/contracts/index.ts` is what `OpenAPILink` is built from. A procedure in59 `router.ts` but not in the contract is server-callable only.6061## A procedure, whole6263```ts64// webapp/lib/orpc/procedures/posts.ts65import { protectedProcedure } from '../base'66import { SecureShortText, SecureId, secureObject } from '../schemas'67import { Errors } from '../errors'6869export const rename = protectedProcedure70 .route({ method: 'POST', path: '/protected/posts/rename' })71 .input(secureObject({ id: SecureId, title: SecureShortText.min(1, 'Title is required') }))72 .handler(async ({ context, input }) => {73 const { data, error } = await context.supabase74 .from('posts')75 .update({ title: input.title })76 .eq('id', input.id)77 .eq('user_id', context.user.id) // RLS also enforces this; the filter keeps the 404 honest78 .select('id, title')79 .single()8081 if (error) throw Errors.internal(error.message)82 if (!data) throw Errors.notFound('Post not found')8384 return { success: true, post: data }85 })8687export const postsRouter = { rename }88```8990Then append `posts: postsRouter` to `protectedRouter` in `procedures/protected.ts`, and add the91matching contract entry if the browser needs to call it.9293## Tiers9495| Builder | Auth | Rate limit key | Use for |96|---|---|---|---|97| `publicProcedure` | none | client IP | health, public reads |98| `authProcedure` | none | client IP, stricter | sign-in, sign-up, password reset |99| `protectedProcedure` | required | user id | everything a signed-in user does |100| `paidProcedure` | required, plan `!== 'free'` | user id | writes free users must not reach |101| `adminProcedure` | required, `role === 'admin'` | user id | admin surfaces |102103The chain is built once in `base.ts`: context init → tracing → Supabase client → rate limit →104Sentry `onError` → logging → analytics, then the tier's own guards.105106## Errors107108| Factory | `e.code` | Status |109|---|---|---|110| `Errors.unauthorized()` | `UNAUTHORIZED` | 401 |111| `Errors.forbidden(msg)` | `FORBIDDEN` | 403 |112| `Errors.notFound(msg)` | `NOT_FOUND` | 404 |113| `Errors.badRequest(msg, { field })` | `BAD_REQUEST` | 400 |114| `Errors.internal(msg)` | `INTERNAL_SERVER_ERROR` | 500 |115| `Errors.validation(msg, { field })` | `VALIDATION_ERROR` | app-defined code |116| `Errors.rateLimited(seconds)` | `RATE_LIMITED` | app-defined code |117118The last two are codes this app invented (`webapp/lib/orpc/errors.ts`), not oRPC standard ones —119branch on `e.code`, never on the status number. A client's 429 comes from the rate-limit plugin.120121## Mutation, end to end122123```ts124// webapp/features/posts/actions.ts125'use server'126import { rename as renameProcedure } from '@/lib/orpc/procedures/posts'127import { buildActionContext, cacheInvalidator } from '@/lib/orpc/action-utils'128129export const renameAction = renameProcedure.actionable({130 context: buildActionContext,131 interceptors: [cacheInvalidator('posts')], // generic <T> is the output type; let it infer132})133```134135```ts136// webapp/features/posts/hooks/index.ts — 'use client'137const mutation = useMutation({138 mutationFn: async (values: RenameValues) => {139 const [error, data] = await renameAction(values)140 if (error) throw new Error(error.message ?? 'Rename failed')141 return data142 },143 onSuccess: () => router.refresh(),144})145```146147`cacheInvalidator` calls `updateTag()` server-side; `router.refresh()` re-renders the server148components. Never `queryClient.invalidateQueries()` for a mutation — the server cache is the source149of truth, and `updateTag()` inside the HTTP handler 500s.150151## Reading152153- Server component: `const caller = await getORPCCaller()` then `caller.protected.settings.getProfile()`.154 It reads cookies, so it is **not** safe inside `use cache` — use `getPublicORPCCaller()` there.155- Client component: `useQuery(orpc.protected.me.queryOptions())`, or `await client.protected.me()`.156 Never fetch in a `useEffect`.157158## List shapes159160`{ items, nextCursor, hasMore }` for cursor, `{ items, page, hasMore, totalCount }` for offset.161Always name the array `items`. Cursor is the default; offset only for admin page-jumping.162`references/pagination.md` has the query and the required index.