بناء واجهات برمجة آمنة النوع باستخدام ORPC و Next.js 15 في 2026

pnpm create next-app@latest orpc-demo --typescript --app --tailwind --src-dir
cd orpc-demo

pnpm add @orpc/server @orpc/client @orpc/contract @orpc/openapi
pnpm add @orpc/react-query @tanstack/react-query
pnpm add zod

// src/server/contract.ts
import { oc } from '@orpc/contract'
import { z } from 'zod'
 
const TaskSchema = z.object({
  id: z.string().uuid(),
  title: z.string().min(1).max(120),
  done: z.boolean(),
  createdAt: z.date(),
})
 
export const contract = oc.router({
  task: {
    list: oc
      .route({ method: 'GET', path: '/tasks' })
      .input(z.object({ cursor: z.string().optional(), limit: z.number().int().min(1).max(100).default(20) }))
      .output(z.object({ items: z.array(TaskSchema), nextCursor: z.string().nullable() })),
 
    create: oc
      .route({ method: 'POST', path: '/tasks' })
      .input(z.object({ title: z.string().min(1).max(120) }))
      .output(TaskSchema),
 
    update: oc
      .route({ method: 'PATCH', path: '/tasks/{id}' })
      .input(z.object({ id: z.string().uuid(), title: z.string().optional(), done: z.boolean().optional() }))
      .output(TaskSchema),
 
    delete: oc
      .route({ method: 'DELETE', path: '/tasks/{id}' })
      .input(z.object({ id: z.string().uuid() }))
      .output(z.object({ success: z.literal(true) })),
  },
})
 
export type Contract = typeof contract

// src/server/router.ts
import { implement } from '@orpc/server'
import { randomUUID } from 'node:crypto'
import { contract } from './contract'
 
type Task = {
  id: string
  title: string
  done: boolean
  createdAt: Date
}
 
const store = new Map<string, Task>()
 
const os = implement(contract)
 
const taskListHandler = os.task.list.handler(async ({ input }) => {
  const items = Array.from(store.values()).slice(0, input.limit)
  return { items, nextCursor: null }
})
 
const taskCreateHandler = os.task.create.handler(async ({ input }) => {
  const task: Task = {
    id: randomUUID(),
    title: input.title,
    done: false,
    createdAt: new Date(),
  }
  store.set(task.id, task)
  return task
})
 
const taskUpdateHandler = os.task.update.handler(async ({ input, errors }) => {
  const existing = store.get(input.id)
  if (!existing) throw errors.NOT_FOUND({ message: 'Task not found' })
  const updated = { ...existing, ...input }
  store.set(updated.id, updated)
  return updated
})
 
const taskDeleteHandler = os.task.delete.handler(async ({ input, errors }) => {
  if (!store.has(input.id)) throw errors.NOT_FOUND({ message: 'Task not found' })
  store.delete(input.id)
  return { success: true as const }
})
 
export const router = os.router({
  task: {
    list: taskListHandler,
    create: taskCreateHandler,
    update: taskUpdateHandler,
    delete: taskDeleteHandler,
  },
})
 
export type Router = typeof router

// src/app/api/[[...rest]]/route.ts
import { RPCHandler } from '@orpc/server/fetch'
import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { router } from '@/server/router'
 
const rpcHandler = new RPCHandler(router)
const openapiHandler = new OpenAPIHandler(router)
 
async function handle(request: Request) {
  const url = new URL(request.url)
 
  if (url.pathname.startsWith('/api/rpc')) {
    const { response } = await rpcHandler.handle(request, { prefix: '/api/rpc' })
    if (response) return response
  }
 
  const { response } = await openapiHandler.handle(request, { prefix: '/api' })
  if (response) return response
 
  return new Response('Not found', { status: 404 })
}
 
export const GET = handle
export const POST = handle
export const PATCH = handle
export const DELETE = handle

// src/lib/orpc-client.ts
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'
import type { Router } from '@/server/router'
 
const link = new RPCLink({ url: '/api/rpc' })
 
export const orpc = createORPCClient<Router>(link)

// src/app/providers.tsx
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState, type ReactNode } from 'react'
 
export function Providers(props: { children: ReactNode }) {
  const [client] = useState(() => new QueryClient())
  return <QueryClientProvider client={client}>{props.children}</QueryClientProvider>
}

// src/app/layout.tsx
import { Providers } from './providers'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

// src/app/page.tsx
'use client'
import { createORPCReactQueryUtils } from '@orpc/react-query'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { useState } from 'react'
import { orpc } from '@/lib/orpc-client'
 
const $orpc = createORPCReactQueryUtils(orpc)
 
export default function HomePage() {
  const qc = useQueryClient()
  const [title, setTitle] = useState('')
 
  const tasks = useQuery($orpc.task.list.queryOptions({ input: { limit: 20 } }))
 
  const createTask = useMutation({
    ...$orpc.task.create.mutationOptions(),
    onSuccess: () => qc.invalidateQueries({ queryKey: $orpc.task.list.key() }),
  })
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">المهام</h1>
 
      <form
        onSubmit={(e) => {
          e.preventDefault()
          createTask.mutate({ title })
          setTitle('')
        }}
        className="mt-4 flex gap-2"
      >
        <input
          value={title}
          onChange={(e) => setTitle(e.target.value)}
          className="flex-1 rounded border px-3 py-2"
          placeholder="ما الذي يجب إنجازه؟"
        />
        <button className="rounded bg-black px-4 py-2 text-white">إضافة</button>
      </form>
 
      <ul className="mt-6 space-y-2">
        {tasks.data?.items.map((task) => (
          <li key={task.id} className="rounded border p-3">
            {task.title}
          </li>
        ))}
      </ul>
    </main>
  )
}

// src/server/middleware.ts
import { os } from './router'
import { ORPCError } from '@orpc/server'
import { cookies } from 'next/headers'
 
export const authed = os.middleware(async ({ context, next }) => {
  const session = (await cookies()).get('session')?.value
  if (!session) throw new ORPCError('UNAUTHORIZED', { message: 'Sign in to continue' })
 
  const user = { id: session, role: 'member' as const }
  return next({ context: { ...context, user } })
})

const taskCreateHandler = os.task.create
  .use(authed)
  .handler(async ({ input, context }) => {
    const task: Task = {
      id: randomUUID(),
      title: `${input.title} (by ${context.user.id})`,
      done: false,
      createdAt: new Date(),
    }
    store.set(task.id, task)
    return task
  })

// src/app/api/openapi/route.ts
import { OpenAPIGenerator } from '@orpc/openapi'
import { ZodToJsonSchemaConverter } from '@orpc/zod'
import { contract } from '@/server/contract'
 
const generator = new OpenAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
})
 
export async function GET() {
  const spec = await generator.generate(contract, {
    info: { title: 'Tasks API', version: '1.0.0' },
    servers: [{ url: '/api' }],
  })
  return Response.json(spec)
}

import { isDefinedError } from '@orpc/client'
 
try {
  await orpc.task.update({ id: 'bad-id', title: 'Nope' })
} catch (error) {
  if (isDefinedError(error) && error.code === 'NOT_FOUND') {
    console.warn('Task disappeared — refresh the list')
  } else {
    throw error
  }
}

pnpm dev

curl http://localhost:3000/api/tasks
curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Finish ORPC tutorial"}'