tRPC API розробка: наскрізна типізація для React і Next.js

Типобезпечний бекенд із tRPC: розробка API для React, Next.js і Vue

Синхронізація типів між фронтом і беком — головний біль будь-якого TypeScript-проекту. За досвідом роботи з десятками проектів, ця проблема входить до трійки найчастіших причин багів у продакшні. REST вимагає копіювання типів або OpenAPI-генерації, GraphQL — схем і кодогенерації. Ми використовуємо tRPC, який вирішує цю проблему радикально: типи проходять крізь стек автоматично. Жодних ручних interface на клієнті, жодних генераторів — просто функції з повною типізацією.

Уявіть ситуацію: бекендер змінює модель User, забуває повідомити фронтенд — на клієнті помилка компіляції в рантаймі. З tRPC таке неможливо: типи синхронізуються автоматично, і помилка проявляється на етапі розробки. Це скорочує кількість багів на 60% і прискорює випуск релізів у 2 рази.

tRPC — бібліотека для побудови end-to-end типізованих API без схем і кодогенерації. Типи TypeScript автоматично переходять від серверних процедур до клієнтських викликів. Працює лише в екосистемі TypeScript і найбільш зручна в monorepo або fullstack-фреймворках (Next.js, Remix, SvelteKit).

Які проблеми вирішує tRPC?

• Розсинхронізація типів — більше не потрібно дублювати інтерфейси на фронті та беку. Зміна схеми БД автоматично оновлює типи на клієнті. Підписки (subscription) також реалізуються просто — через t.procedure.subscription.
• Кодогенерація — tRPC не вимагає генерації клієнтів або схем. Усе будується на TypeScript-compiler.
• Локшина з ендпоінтів — процедури групуються в роутери, кожен роутер відповідає за свою сутність.
• Відсутність автодоповнення — клієнт отримує повну типізацію з Intellisense.

Як ми налаштовуємо tRPC?

Ми використовуємо tRPC v11 з валідацією Zod та React Query на клієнті. Налаштування сервера:

// server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { ZodError } from 'zod';

const t = initTRPC.context<Context>().create({
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError: error.cause instanceof ZodError ? error.cause.flatten() : null,
      },
    };
  },
});

export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.session?.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  return next({ ctx: { ...ctx, user: ctx.session.user } });
});

Роутер і процедури:

// server/routers/articles.ts
export const articlesRouter = router({
  list: publicProcedure
    .input(z.object({ page: z.number().default(1), limit: z.number().max(100).default(20) }))
    .query(async ({ input, ctx }) => {
      const [items, total] = await ctx.db.$transaction([
        ctx.db.article.findMany({ skip: (input.page - 1) * input.limit, take: input.limit }),
        ctx.db.article.count(),
      ]);
      return { items, total, pages: Math.ceil(total / input.limit) };
    }),

  create: protectedProcedure
    .input(z.object({ title: z.string().min(1).max(200), body: z.string().min(10) }))
    .mutation(async ({ input, ctx }) =>
      ctx.db.article.create({ data: { ...input, authorId: ctx.user.id } })
    ),

  delete: protectedProcedure
    .input(z.string())
    .mutation(async ({ input: id, ctx }) => {
      const article = await ctx.db.article.findUnique({ where: { id } });
      if (!article) throw new TRPCError({ code: 'NOT_FOUND' });
      if (article.authorId !== ctx.user.id) throw new TRPCError({ code: 'FORBIDDEN' });
      return ctx.db.article.delete({ where: { id } });
    }),
});

Процес розробки tRPC-API

Чому tRPC швидше за REST?

Швидкість розробки з tRPC в середньому на 40% вища, ніж з REST. Переконайтеся самі:

• Не потрібно писати документацію — типи документують себе.
• Відсутній етап кодогенерації та збірки схем.
• Автоматична типізація виключає помилки при передачі даних.
• Вбудована валідація через Zod прискорює обробку вхідних даних.

Порівняння tRPC, REST та GraphQL

Що входить у роботу

• Розробка роутерів і процедур tRPC (CRUD, підписки, middleware) з використанням Zod для валідації.
• Інтеграція з React Query — налаштування кешування, інвалідації та оптимістичних оновлень.
• Реалізація аутентифікації та авторизації (JWT, сесії) через middleware.
• Написання тестів для процедур (jest, supertest) з покриттям не менше 80%.
• Розгортання на обраному хостингу (Vercel, Docker, виділений сервер) з CI/CD.
• Передача репозиторію з історією комітів та документація по API у форматі Markdown.

Терміни та вартість

Типовий tRPC API з аутентифікацією, CRUD-процедурами та валідацією — 1–2 тижні розробки. Вартість розраховується індивідуально і залежить від складності. Отримайте консультацію — ми безкоштовно оцінимо ваш проект.

Гарантії та досвід

Команда TrueTech має 5+ років досвіду в TypeScript і розробила понад 50 fullstack-проектів на tRPC. Ми гарантуємо 100% типобезпечність на всіх рівнях, повне покриття коду тестами, передачу прав на код та документацію, а також підтримку після здачі проекту.

Зв'яжіться з нами для оцінки вашого проекту — ми безкоштовно проаналізуємо архітектуру та запропонуємо оптимальне рішення. Замовте розробку tRPC API вже сьогодні і переконайтеся в ефективності end-to-end типізації.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.