Добро пожаловать в приложение на TanStack!

Быстрый старт

Запуск проекта в dev-режиме:

bun dev

Сборка production:

bun build

Тесты (если есть):

bun test

Стек и архитектура

• Kubb: генерация типов/клиентов/хуков/Zod-схем из OpenAPI (./spec/openapi.yaml).
• HTTP-клиент: кастомный axios с AbortController и корректной сериализацией query.
• Виртуальный роутинг: TanStack Router + плагин генерации маршрутов из файлов конфигурации.
• TanStack Query: сгенерированные хуки для запросов/мутаций.
• Zod: рантайм-валидация ответов API и схемы для форм.
• UI: Tailwind CSS, shadcn/ui, class-variance-authority (CVA).

Виртуальный роутинг

Мы используем виртуальный роутинг через @tanstack/router-plugin.

• Конфигурация виртуальных маршрутов: src/routes/routes.ts (описание дерева).
• Лайауты и страницы лежат в src/routes/**, но файлы-«маршруты» должны экспортировать Route через createFileRoute.
• Примеры:
  • Лайауты: src/routes/layouts/main.tsx, src/routes/layouts/auth.tsx
  • Главная: src/routes/main/index.tsx
  • Пример страницы поиска питомцев: src/routes/main/pets.tsx

Пример определения страницы:

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/_main/pets")({
  component: () => <div>Pets</div>,
});

HTTP‑клиент и прокси

• Клиент: src/lib/http/client.ts
  • Базовый URL: VITE_API_BASE_URL или /api
  • Поддержка AbortController (signal), корректная сериализация массивов (multi: status=a&status=b)
• Прокси dev‑сервера: vite.config.ts

Генерация через Kubb

Конфиг: kubb.config.ts. Подключены плагины:

• @kubb/plugin-oas — парсинг OpenAPI
• @kubb/plugin-ts — типы (src/gen/types)
• @kubb/plugin-client — клиенты (src/gen/clients) на базе кастомного axios; parser: 'zod'
• @kubb/plugin-react-query — хуки (src/gen/hooks) c parser: 'zod'
• @kubb/plugin-zod — схемы (src/gen/zod)

Команда:

bun run generate

Флоу обновления:

1. Обновить/скачать спецификацию в ./spec/openapi.yaml (скрипт bun run download-spec при желании).
2. Запустить bun run generate — обновятся типы/клиенты/хуки/схемы.
3. Использовать сгенерированный код в приложении.

Использование TanStack Query

• GET (пример):

import { useFindPetsByStatus } from "@/gen/hooks/petHooks/useFindPetsByStatus";

const { data, isLoading, error } = useFindPetsByStatus({
  status: ["available"],
});

• Мутация (пример):

import { useCreateUser } from "@/gen/hooks/userHooks/useCreateUser";

const m = useCreateUser();
m.mutate({
  /* payload */
});

• Отмена запроса:

const c = new AbortController();
await createUser(body, { signal: c.signal });
c.abort();

Zod: валидация и формы

Сгенерированные схемы лежат в src/gen/zod/** и используются для рантайм‑валидации ответов клиентов/хуков.

Утилиты для форм/ошибок: src/lib/http/zod-helpers.ts

• isAxiosError, extractAxiosError
• mapErrorObjectToFormErrors, mapZodIssuesToFormErrors, toSetErrorPayload
• InferForm<T>

Интеграция с React Hook Form:

import type { InferForm } from "@/lib/http/zod-helpers";
import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { userSchema } from "@/gen/zod/userSchemas";

const form = useForm<InferForm<typeof userSchema>>({
  resolver: zodResolver(userSchema),
});

Команды

• Генерация Kubb: bun run generate
• Запуск dev: bun dev
• Сборка: bun build
• Тесты: bun test

UI (Tailwind, shadcn/ui, CVA)

• Tailwind CSS уже подключён; стили глобально в src/styles.css.
• shadcn/ui можно добавлять командами:

  bunx shadcn@latest add button

• CVA (class-variance-authority) используем для вариативных классов в компонентах.

Пример CVA:

import { cva } from "class-variance-authority";

export const button = cva("inline-flex items-center rounded px-3 py-2", {
  variants: {
    variant: { primary: "bg-blue-600 text-white", ghost: "bg-transparent" },
    size: { sm: "text-sm", md: "text-base" },
  },
  defaultVariants: { variant: "primary", size: "md" },
});

Полезные пути

• Конфиг Kubb: front/kubb.config.ts
• Спека OpenAPI: front/spec/openapi.yaml
• Генерация: front/src/gen/**
• Клиент: front/src/lib/http/client.ts
• Zod helpers: front/src/lib/http/zod-helpers.ts
• Роутинг: front/src/routes/**, дерево — front/src/routes/routes.ts