Знакомьтесь, tRPC / Хабр

Hello, world!

В этом туториале мы разработаем простое типобезопасное (typesafe) клиент-серверное (fullstack) приложение с помощью tRPC, React и Express.

tRPC позволяет разрабатывать полностью безопасные с точки зрения типов API для клиент-серверных приложений (предпочтительной является архитектура монорепозитория). Это посредник между сервером и клиентом, позволяющий им использовать один маршрутизатор (роутер) для обработки запросов HTTP. Использование одного роутера, в свою очередь, обуславливает возможность автоматического вывода типов (type inference) входящих и исходящих данных (input/output), что особенно актуально для клиента и позволяет избежать дублирования типов или использования общих (shared) типов.

Руководство по tRPC находится в процессе подготовки — следите за обновлениями ?

Для тех, кого интересует только код, вот ссылка на соответствующий репозиторий.

Интересно? Тогда прошу под кат.

Подготовка и настройка проекта

Функционал нашего приложения будет следующим:

на сервере хранится массив с данными пользователей;
на сервере есть конечные точки (endpoints) для:
- получения всех пользователей;
- получения одного пользователя по идентификатору;
- создания нового пользователя;
клиент запрашивает всех пользователей и рендерит список их имен;
на клиенте есть форма для запроса одного пользователя по ID;
на клиенте есть форма для создания нового пользователя.

Как видите, все очень просто. Давайте это реализуем.

Архитектура монорепозитория предполагает, что код клиента и сервера "живет" в одной директории (репозитории).

Создаем корневую директорию:

mkdir trpc-fullstack-app
cd trpc-fullstack-app

Создаем директорию для сервера:

mkdir server
cd server

Обратите внимание: для работы с зависимостями будет использоваться Yarn.

Инициализируем проект Node.js:

yarn init -yp

Устанавливаем основные зависимости:

yarn add express cors

Поскольку клиент и сервер будут иметь разные источники (origins) (будут запускаться на разных портах), "общение" между ними будет блокироваться CORS. Пакет cors позволяет настраивать эту политику.

Устанавливаем зависимости для разработки:

yarn add -D typescript @types/express @types/cors

Создаем файл tsconfig.json следующего содержания:

{
  "compilerOptions": {
    "allowJs": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    // директория сборки
    "outDir": "./dist",
    // директория исходников
    "rootDir": "./src",
    "skipLibCheck": true,
    "strict": true,
    "target": "es2019"
  }
}

Редактируем файл package.json:

{
  // ...
  // основной файл сервера
  "main": "dist/index.js",
  // модули ES
  "type": "module",
  "scripts": {
    // компиляция TS в JS с наблюдением за изменениями файлов
    "ts:watch": "tsc -w",
    // запуск сервера с перезагрузкой после изменений
    "node:dev": "nodemon",
    // одновременное выполнение команд
    // мы установим concurrently на верхнем уровне
    "start": "concurrently \"yarn ts:watch\" \"yarn node:dev\"",
    // производственная сборка
    "build": "tsc --build && node dist/index.js"
  }
}

Создаем директорию src и дальше работаем с ней.

Создаем файл index.ts следующего содержания:

import express from 'express'
import cors from 'cors'

const app = express()

app.use(cors())

// адрес сервера: http://localhost:4000
app.listen(4000, () => {
  console.log('Server running on port 4000')
})

Определяем тип пользователя в файле users/types.ts:

export type User = {
  id: string
  name: string
}

Создаем массив пользователей в файле users/db.ts:

import type { User } from './types'

export const users: User[] = [
  {
    id: '0',
    name: 'John Doe',
  },
  {
    id: '1',
    name: 'Richard Roe',
  },
]

Возвращаемся в корневую директорию и создаем шаблон клиента с помощью Vite:

# client - название проекта/директории
# react-ts - используемый шаблон
yarn create vite client --template react-ts

Vite автоматически настраивает все необходимое, нашего участия в этом процессе не требуется ?

Обратите внимание: клиент будет запускаться по адресу http://localhost:5173

Находясь в корневой директории, инициализируем проект Node.js устанавливаем concurrently:

yarn init -yp
yarn add concurrently

Определяем в package.json команду для одновременного запуска сервера и клиента:

{
  // ...
  "scripts": {
    "dev": "concurrently \"yarn --cwd ./server start\" \"yarn --cwd ./client dev\""
  }
}

Это все, что требуется для подготовки и настройки проекта. Переходим к доработке сервера.

Сервер

Нам потребуется еще 2 пакета:

yarn add @trpc/server zod

@trpc/server — пакет для разработки конечных точек и роутеров;
zod — пакет для валидации данных.

Далее работаем с директорией src.

Создаем файл trpc.ts с кодом инициализации tRPC:

import { initTRPC } from '@trpc/server'
import type { Context } from './context'

const t = initTRPC.context<Context>().create()

export const router = t.router
export const publicProcedure = t.procedure

Определяем контекст tRPC в файле context.ts:

import { inferAsyncReturnType } from '@trpc/server'
import * as trpcExpress from '@trpc/server/adapters/express'

const createContext = ({
  req,
  res,
}: trpcExpress.CreateExpressContextOptions) => {
  return {}
}

export type Context = inferAsyncReturnType<typeof createContext>

export default createContext

Определяем корневой роутер/роутер приложения tRPC в файле router.ts:

import { router } from './trpc.js'
import userRouter from './user/router.js'

const appRouter = router({
  user: userRouter,
})

export default appRouter

Для подключения tRPC к серверу используется обработчик запросов или адаптер. Редактируем файл index.ts:

// ...
import * as trpcExpress from '@trpc/server/adapters/express'
import appRouter from './router.js'
import createContext from './context.js'

// ...
app.use(cors())

app.use(
  // суффикс пути
  // получаем http://localhost:4000/trpc
  '/trpc',
  trpcExpress.createExpressMiddleware({
    router: appRouter,
    createContext,
  }),
)

// ...

// обратите внимание: экспортируется не сам роутер, а только его тип
export type AppRouter = typeof appRouter

Наконец, определяем конечные точки пользователей в файле users/router.ts:

import { z } from 'zod'
import { router, publicProcedure } from '../trpc.js'
import { users } from './db.js'
import type { User } from './types'
import { TRPCError } from '@trpc/server'

const userRouter = router({
  // обработка запроса на получение всех пользователей
  // выполняем запрос (query)
  getUsers: publicProcedure.query(() => {
    // просто возвращаем массив
    return users
  }),
  // обработка запроса на получение одного пользователя по ID
  getUserById: publicProcedure
    // валидация тела запроса
    // ID должен быть строкой
    .input((val: unknown) => {
      if (typeof val === 'string') return val

      throw new TRPCError({
        code: 'BAD_REQUEST',
        message: `Invalid input: ${typeof val}`,
      })
    })
    .query((req) => {
      const { input } = req

      // ищем пользователя
      const user = users.find((u) => u.id === input)

      // если не нашли, выбрасываем исключение
      if (!user) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: `User with ID ${input} not found`,
        })
      }

      // если нашли, возвращаем его
      return user
    }),
  // обработка создания нового пользователя
  createUser: publicProcedure
    // тело запроса должно представлять собой объект с полем `name`,
    // значением которого должна быть строка
    .input(z.object({ name: z.string() }))
    // выполняем мутацию
    .mutation((req) => {
      const { input } = req

      // создаем пользователя
      const user: User = {
        id: `${Date.now().toString(36).slice(2)}`,
        name: input.name,
      }

      // добавляем его в массив
      users.push(user)

      // и возвращаем
      return user
    }),
})

export default userRouter

Финальная структура директории server:

- node_modules
- src
  - user
    - db.ts
    - router.ts
    - types.ts
  - context.ts
  - index.ts
  - router.ts
  - trpc.ts
- package.json
- tsconfig.json
- yarn.lock

Наш сервер полностью готов к обработке запросов клиента.

Клиент

Здесь нам также потребуется еще 2 пакета.

# client
yarn add @trpc/client @trpc/server

Возможно, мы могли установить @trpc/server на верхнем уровне ?

Далее работаем с директорией src.

Создаем файл trpc.ts с кодом инициализации tRPC:

import { createTRPCProxyClient, httpBatchLink } from '@trpc/client'
// здесь могут возникнуть проблемы при использовании синонимов путей (type aliases)
import { AppRouter } from '../../server/src/index'

export const trpc = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:4000/trpc',
    }),
  ],
})

Для начала давайте просто выведем список пользователь в консоль инструментов разработчика в браузере. Редактируем файл App.tsx следующим образом:

import { useEffect } from 'react'
import { trpc } from './trpc'

function App() {
  useEffect(() => {
    trpc.user.getUsers.query()
      .then(console.log)
      .catch(console.error)
  }, [])

  return (
    <div></div>
  )
}

export default App

Запускаем приложение. Это можно сделать 2 способами:

выполнить команду yarn dev из корневой директории;
выполнить команду yarn start из директории server и команду yarn dev из директории client.

Результат:

Многим React-разработчикам (и мне, в том числе) нравится библиотека React Query, позволяющая легко получать, кэшировать и модифицировать данные. К счастью, tRPC предоставляет абстракцию над React Query. Устанавливаем еще 2 пакета:

yarn add @tanstack/react-query @trpc/react-query

Редактируем файл trpc.ts:

import { createTRPCReact, httpBatchLink } from '@trpc/react-query'
import { AppRouter } from '../../server/src/index'

export const trpc = createTRPCReact<AppRouter>()

export const trpcClient = trpc.createClient({
  links: [
    httpBatchLink({
      url: 'http://localhost:4000/trpc',
    }),
  ],
})

Редактируем файл main.tsx:

// ...
import App from './App'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { trpc, trpcClient } from './trpc'

const queryClient = new QueryClient()

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        <App />
      </QueryClientProvider>
    </trpc.Provider>
  </React.StrictMode>,
)

Получим пользователей и отрендерим их имена в App.tsx:

function App {
  const {
    data: usersData,
    isLoading: isUsersLoading,
  } = trpc.user.getUsers.useQuery()

  if (isUsersLoading) return <div>Loading...</div>

  return (
    <div>
      <ul>
        {(usersData ?? []).map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  )
}

Результат:

Добавляем форму для получения одного пользователя по ID:

function App() {
  // ...

  const [userId, setUserId] = useState('0')
  const {
    data: userData,
    isLoading: isUserLoading,
    error,
  } = trpc.user.getUserById.useQuery(userId, {
    retry: false,
    refetchOnWindowFocus: false,
  })

  if (isUsersLoading || isUserLoading) return <div>Loading...</div>

  const getUserById: React.FormEventHandler = (e) => {
    e.preventDefault()
    const input = (e.target as HTMLFormElement).elements[0] as HTMLInputElement
    const userId = input.value.replace(/\s+/g, '')
    if (userId) {
      // обновление состояния ID пользователя приводит к выполнению нового/повторного запроса
      setUserId(userId)
    }
  }

  return (
    <div>
      {/* ... */}
      <div>
        <form onSubmit={getUserById}>
          <label>
            Get user by ID <input type='text' defaultValue={userId} />
          </label>
          <button>Get</button>
        </form>
        {/* Если пользователь найден */}
        {userData && <div>{userData.name}</div>}
        {/* Если пользователь не найден */}
        {error && <div>{error.message}</div>}
      </div>
    </div>
  )
}

Результат:

Наконец, добавляем форму для создания нового пользователя:

function App() {
  const {
    data: usersData,
    isLoading: isUsersLoading,
    // метод для ручного повторного выполнения запроса
    refetch,
  } = trpc.user.getUsers.useQuery()

  // ...

  // Состояние для имени пользователя
  const [userName, setUserName] = useState('Some Body')
  // Мутация для создания пользователя
  const createUserMutation = trpc.user.createUser.useMutation({
    // После выполнения мутации необходимо повторно запросить список пользователей
    onSuccess: () => refetch(),
  })

  // ...

  // Обработка отправки формы для создания нового пользователя
  const createUser: React.FormEventHandler = (e) => {
    e.preventDefault()
    const name = userName.trim()
    if (name) {
      createUserMutation.mutate({ name })
      setUserName('')
    }
  }

  return (
    <div>
      {/* ... */}
      <form onSubmit={createUser}>
        <label>
          Create new user{' '}
          <input
            type='text'
            value={userName}
            onChange={(e) => setUserName(e.target.value)}
          />
        </label>
        <button>Create</button>
      </form>
    </div>
  )
}

Результат:

На этом разработку нашего приложения можно считать завершенной.

Надеюсь, вы узнали что-то новое и не зря потратили время.

Happy coding!

Знакомьтесь, tRPC

Подготовка и настройка проекта

Сервер

Клиент

Публикации

Информация