Struktura projektu

Drzewo katalogów

combo-raport-app/
├── src/
│   ├── App.tsx                      # główny komponent aplikacji
│   ├── main.tsx                     # punkt wejścia React (root render)
│   ├── index.css                    # globalne style, zmienne CSS Tailwind
│   ├── components/
│   │   ├── theme-provider.tsx       # kontekst dark/light/system + skrót klawiszowy D
│   │   └── ui/                      # komponenty shadcn/ui
│   │       ├── table.tsx
│   │       ├── checkbox.tsx
│   │       ├── switch.tsx
│   │       ├── button.tsx
│   │       ├── tooltip.tsx
│   │       └── ...
│   └── lib/
│       └── utils.ts                 # cn() = clsx + tailwind-merge
├── public/
│   └── data/
│       ├── T1/                      # wolumen miesięczny (ReportRow[])
│       ├── T2/                      # KPI miesięczne (KpiRow[])
│       └── T5/                      # sprzedaż YTD (ReportRow[])
├── docker/
│   └── nginx.conf                   # konfiguracja nginx (tryb prod)
├── Dockerfile                       # multi-stage build
├── docker-compose.yml               # profile dev/prod
├── .dockerignore
├── vite.config.ts                   # Vite + pluginy
├── tsconfig.json                    # TypeScript (references do app i node)
├── tsconfig.app.json
├── tsconfig.node.json
├── eslint.config.js                 # ESLint flat config
├── .prettierrc                      # Prettier
├── components.json                  # konfiguracja shadcn CLI
├── package.json
├── pnpm-lock.yaml
└── pnpm-workspace.yaml              # allowBuilds (esbuild, msw)

Stack technologiczny

Warstwa	Biblioteka / Narzędzie	Wersja
UI framework	React	19
Style	Tailwind CSS	4
Komponenty	shadcn/ui, Base UI	—
Tabele	TanStack Table	v8
Ikony	Phosphor Icons, Lucide React	—
Build	Vite	7
Język	TypeScript	5.9
Package manager	pnpm	10
Fonty	JetBrains Mono Variable, Noto Sans Variable	—
Kontener	Docker Desktop, nginx	1.27-alpine

Skrypty pnpm

pnpm dev          # serwer developerski Vite (port 5173)
pnpm build        # tsc -b && vite build → dist/
pnpm preview      # nginx-like preview zbudowanego dist/ (port 4173)
pnpm lint         # ESLint na całym projekcie
pnpm format       # Prettier --write na *.ts i *.tsx
pnpm typecheck    # tsc --noEmit (samo sprawdzenie typów, bez buildu)

Vite — pluginy

Plugin	Rola
`@vitejs/plugin-react`	JSX transform, Fast Refresh
`@tailwindcss/vite`	Tailwind CSS v4 jako Vite plugin
`vite-tsconfig-paths`	aliasy `@/` z tsconfig
`vite-plugin-svgr`	import SVG jako React komponent
`vite-plugin-checker`	TypeScript + ESLint overlay w trakcie dev
`vite-plugin-live-reload`	przeładowanie na zmianę plików JSON w `public/data/`
`vite-plugin-watch-and-run`	full-reload przez WS po zmianie JSON
`rollup-plugin-visualizer`	generuje `stats.html` z analizą bundle

stats.html generuje się po każdym pnpm build. Otwórz go w przeglądarce żeby zobaczyć rozkład rozmiarów modułów.

Aliasy ścieżek

// tsconfig.app.json + vite.config.ts
"@/*" → "./src/*"

Przykład: import { cn } from "@/lib/utils"

Konfiguracja shadcn

Plik components.json określa:

styl: default
katalog komponentów: src/components/ui
aliasy CSS: @/

Dodawanie nowych komponentów:

npx shadcn@latest add <nazwa>
# np. npx shadcn@latest add dialog