Observer

Фронтенд

Стек

НапрямокВибір
ФреймворкReact 19 + React Compiler
ЗбірникVite 6
Пакетний менеджерBun (workspace monorepo)
МаршрутизаціяTanStack Router (file-based)
Отримання данихTanStack Query v5
СтилізаціяTailwind CSS v4
Headless UIBase UI (@base-ui/react)
ІконкиPhosphor Icons (@phosphor-icons/react)
i18ni18next + react-i18next
Перевірка типівTypeScript 5.7 (strict)

Структура проєкту

packages/observer-web/
  src/
    main.tsx          # app bootstrap (Router + Query + i18n)
    main.css          # Tailwind entry
    routes/           # TanStack Router file-based routes (_app/, _auth/)
    components/       # UI components, grouped by domain
      ui/             # atoms: button, badge, icons, toast…
      layout/         # app shell: page-header, sidebar-link…
      forms/          # form-field, filter-bar, comboboxes
      table/          # data-table, pagination, row-actions
      dialogs/        # confirm-dialog, form-dialog
      drawer/         # drawer-shell
      people/ pets/ support/ households/ migration/
      documents/ tags/ users/ permissions/ profile/
      reports/ charts/ auth/ date-picker/ search-palette/
    hooks/            # React Query hooks, grouped by domain
      reference/      # countries, states, places, offices, categories
      people/ pets/ support/ households/ migration/
      documents/ tags/ notes/ users/ projects/ reports/
    stores/           # Zustand: auth, toast
    types/            # TypeScript types matching API responses
    lib/              # api client, i18n, export, params helpers
    constants/        # enum → i18n key maps
    locales/          # ky.json (default), en.json, uk.json, ru.json…

Запуск

# Install dependencies
cd packages/observer-web && bun install

# Backend + frontend dev servers concurrently
just dev

# Frontend only (http://localhost:5173)
cd packages/observer-web && bun run dev

# Production build (frontend + embedded Go binary)
just build-prod

# Format frontend code
cd packages/observer-web && bun run fmt

Конвенції імпортів

Аліас @/ вказує на src/. Налаштовано як у tsconfig.json, так і у vite.config.ts.

Порядок імпортів (порожній рядок між групами):

  1. react, react-dom
  2. Зовнішні бібліотеки (@tanstack/*, @base-ui/*, @phosphor-icons/*, i18next)
  3. Аліаси застосунку (@/lib/*, @/stores/*, @/types/*)
  4. Сусідні файли (./constants, ./types)
  5. Стилі (.module.css) — завжди останніми

Додавання нового маршруту

  1. Створіть файл у src/routes/. Vite-плагін TanStack Router автоматично генерує дерево маршрутів.
  2. Захищені маршрути розміщуються у _app/ (потребують автентифікації).
  3. Публічні маршрути автентифікації розміщуються у _auth/ (перенаправляють, якщо вже автентифікований).

Приклад:

// src/routes/_app/settings.tsx → /settings (protected)
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/_app/settings")({
  component: SettingsPage,
});

function SettingsPage() {
  return <div>Settings</div>;
}

Додавання перекладів

  1. Додайте ключі до обох файлів src/locales/ky.json та src/locales/en.json.
  2. Використовуйте в компонентах через useTranslation():
import { useTranslation } from "react-i18next";

function MyComponent() {
  const { t } = useTranslation();
  return <p>{t("namespace.key")}</p>;
}

Інтерполяція використовує синтаксис {{variable}} у JSON:

{ "greeting": "Salam, {{name}}" }
t("greeting", { name: "Ali" }); // → "Salam, Ali"

Змінні середовища

ЗміннаЗа замовчуваннямОпис
VITE_API_URLhttp://localhost:9000Базова URL-адреса API бекенду

Vite експонує лише змінні з префіксом VITE_.

Назад
Демонстраційне налаштування
Далі
Довідник CLI