Přeskočit na hlavní obsah
VímŽeNicNevím.czSoftware & Blog
Zpět na přehled

VímŽeNicNevím.cz - Tech Stack a Architektura Projektu

2025-12-22
tech-stacktanstack-startreacttypescriptarchitecturesecurity
10 min čtení

"Jediné, co vím, je, že nic nevím." — Sokrates (a každý Senior Developer)

Osobní blog a digitální zahrada zaměřená na paradox expertízy v softwarovém inženýrství. Místo pro dokumentaci slepých uliček, technických deep-dives a hledání pokory v nekonečném světě JavaScriptu.

🚀 O projektu

Tento web není postaven na Next.js, jak by se v roce 2025 slušelo. Je to experimentální hřiště postavené na TanStack Start — moderním full-stack frameworku od tvůrců TanStack Query a TanStack Router. Projekt slouží jako důkaz konceptu (PoC) pro type-safe React aplikace s důrazem na Developer Experience, bezpečnost a moderní vývojářské workflow.

Aplikace je navržena jako single-page application s server-side rendering (SSR), která kombinuje rychlost klientské interakce s SEO benefity serverového renderování. Celý stack je postaven na moderních nástrojích, které jsou často přehlíženy ve prospěch "velkých hráčů", ale nabízejí větší kontrolu a flexibilitu.

🛠 Tech Stack

Core Framework & Language

  • Framework: TanStack Start 1.159.5

    • Full-stack React framework s built-in SSR/SSG
    • File-based routing s automatickou code-splitting
    • Type-safe data loading s loaders a actions
    • Streaming SSR pro optimální performance

  • React: 19.2.4

    • React 19 s novými features (Server Components, Actions)
    • Concurrent rendering pro lepší UX

  • TypeScript: 5.9.3

    • Striktní typová kontrola (strict: true)
    • Type-safe routing a data fetching
    • Automatická inference typů pro lepší DX

Routing & Navigation

  • TanStack Router: 1.159.5
    • Type-safe routing bez "magic strings"
    • Nested layouts a route groups
    • Automatic route-based code splitting
    • Built-in search params validation
    • Pre-loading strategies pro instant navigation

Styling & UI

  • Tailwind CSS: 4.1.18

    • Utility-first CSS framework
    • JIT (Just-In-Time) compiler pro minimální bundle size
    • Custom design tokens a theme extensions
    • @tailwindcss/typography: Plugin pro krásnou typografii v MDX obsahu

  • Lucide React: 0.563.0

    • Moderní, konzistentní icon library
    • Tree-shakeable a optimalizovaná pro bundle size

  • Motion: 12.34.0

    • Declarative animations pro React
    • Smooth transitions a micro-interactions

  • @lottiefiles/dotlottie-react: 0.17.14

    • Podpora pro komplexní Lottie animace
    • Optimalizované pro web performance

Obsah & Markdown

  • react-markdown: 10.1.0
    • Renderování Markdown obsahu jako React komponenty
    • rehype-highlight: 7.0.2 — Syntax highlighting pro code blocks
    • highlight.js: 11.11.1 — Zvýrazňování kódu s podporou pro 200+ jazyků
    • gray-matter: 4.0.3 — Parsing frontmatter z MDX souborů (metadata článků)

Monitoring & Error Tracking

  • Sentry: @sentry/tanstackstart-react 10.38.0

    • Real-time error tracking a performance monitoring
    • Source maps pro debugging produkčních errorů
    • Session replay pro analýzu user experience
    • Custom error boundaries pro graceful error handling
    • Integrace s TanStack Start pro SSR error tracking

  • UptimeRobot:

    • Monitoring dostupnosti aplikace (external service)
    • Upozornění na downtime přes email/SMS/aplikace
    • Performance metrics a response time tracking

Testing & Quality Assurance

  • Vitest: 4.0.18

    • Unit testing framework kompatibilní s Vite
    • Fast execution díky native ESM
    • @vitest/browser-playwright: 4.0.18 — Browser testing s Playwright
    • @testing-library/react: 16.3.2 — Testing utilities pro React
    • @testing-library/jest-dom: 6.9.1 — Custom matchers pro DOM assertions
    • @vitest/coverage-v8: 4.0.18 — Code coverage reporting
    • jsdom: 28.0.0 — DOM simulation pro unit testy

  • Playwright: 1.58.2

    • End-to-end testing v reálných browserech
    • Cross-browser testing (Chromium, Firefox, WebKit)

Development Tools

  • Storybook: 10.2.8

    • Component-driven development environment
    • @storybook/react-vite: Vite integration pro fast refresh
    • @storybook/addon-docs: Automatická dokumentace komponent
    • @storybook/addon-a11y: Accessibility testing v real-time
    • @storybook/addon-vitest: Integrace Vitest testů do Storybooku
    • @chromatic-com/storybook: Visual regression testing

  • ESLint: 10.0.0

    • Static code analysis pro konzistenci kódu
    • typescript-eslint: 8.55.0 — TypeScript-specific pravidla
    • eslint-plugin-react: 7.37.5 — React best practices
    • eslint-plugin-react-hooks: 7.0.1 — Validace React Hooks pravidel
    • eslint-plugin-interface-to-type: 1.1.0 — Vlastní pravidlo pro vynucení type místo interface
    • eslint-plugin-storybook: 10.2.8 — Storybook-specific linting

  • Vite: 7.3.1

    • Lightning-fast dev server s Hot Module Replacement (HMR)
    • Optimalizovaný production build s Rollup
    • @vitejs/plugin-react: 5.1.4 — React Fast Refresh support
    • vite-tsconfig-paths: 6.1.0 — Support pro TypeScript path aliases

Dependency Management & Security

  • pnpm: 10.29.2

    • Rychlý, disk-efficient package manager
    • Strict node_modules structure pro zabránění phantom dependencies
    • ignore-scripts=true v .npmrc — Blokace postinstall skriptů pro prevenci supply chain útoků

  • Renovate Bot:

    • Automatické dependency updates každé pondělí ráno
    • Grouping souvisejících balíčků (React core, ESLint)
    • Pinned versions pro konzistenci napříč prostředími
    • Automatické merging vypnuté pro manuální review

📦 Klíčové Funkcionalita

1. Type-Safe Routing

Díky TanStack Routeru neexistují "broken links". Každá route je plně typovaná — pokud cesta není definována v typu aplikace, TypeScript zakáže kompilaci. To eliminuje runtime chyby způsobené překlepem v URL nebo odkazem na neexistující stránku.

// ❌ Chyba při kompilaci - cesta neexistuje
<Link to="/neexistujici-stranka">Link</Link>

// ✅ Typovaný link s autocomplete
<Link to="/blog/$slug" params={{ slug: "typescript-tips" }}>Článek</Link>

2. Server-Side Rendering (SSR) & Streaming

Aplikace využívá plný potenciál SSR pro:

  • SEO optimalizaci — crawlery vidí plně renderovaný HTML
  • Rychlejší First Contentful Paint (FCP) — uživatel vidí obsah bez čekání na JS
  • Streaming — progresivní rendering dlouhých stránek (blog posts)
  • Hydration — React převezme kontrolu po načtení na klientu

3. Bezpečnostní Strategie (Supply Chain Security)

Projekt používá agresivní nastavení pro minimalizaci rizika kompromitovaných npm balíčků:

  • .npmrc: ignore-scripts=true

    • Blokuje všechny postinstall/preinstall skripty
    • Prevence proti malicious code injection přes npm packages
    • Manuální kontrola nutných skriptů před povolením

  • Renovate Bot

    • Pravidelné dependency updates každé pondělí
    • Grouping balíčků pro přehlednost (React, ESLint)
    • Pinned versions strategie pro stabilitu
    • Manuální review před merge

  • Sentry Error Tracking

    • Monitoring produkčních errorů v real-time
    • Alerting při spike v error rate
    • Source maps pro debugging minifikovaného kódu

4. Content Management s MDX

Blog články jsou psány v MDX (Markdown + JSX), což umožňuje:

  • Vložení React komponent přímo do Markdown obsahu
  • Syntax highlighting kódu přes highlight.js
  • Frontmatter pro metadata (title, date, tags, description)
  • Type-safe import článků s automatickým generováním seznamu
---
title: "Jak funguje TanStack Router"
date: "2025-01-15"
tags: ["react", "typescript", "routing"]
---

# Článek

<InteractiveDemo />

\`\`\`typescript
const demo = "highlighted code"
\`\`\`

5. Component-Driven Development

Storybook umožňuje vývoj komponent v izolaci:

  • Dokumentace komponent s automaticky generovanými prop tabulkami
  • Visual regression testing přes Chromatic
  • Accessibility testing v real-time (a11y addon)
  • Integration testing s Vitest přímo ve Storybooku

6. Vlastní ESLint Pravidla

Součástí projektu je vlastní ESLint plugin eslint-plugin-interface-to-type:

  • Vynucuje type aliasy místo interface deklarací
  • Konzistence v celé codebase (důležité pro union types a intersections)
  • Publikován na npm jako open-source balíček
  • Automatické fixery pro snadnou migraci

7. Performance Monitoring

  • Sentry Performance Monitoring:

    • Tracking page load times
    • Measuring React component render performance
    • Database query performance (pokud použito)
    • Custom transactions pro business-critical operace

  • UptimeRobot:

    • 5-minutové interval checks dostupnosti
    • Multi-location monitoring (EU, US, Asia)
    • Status page pro uživatele
    • Incident timeline a downtime statistics

🏃‍♂️ Jak spustit lokálně

Prerequisites

  • Node.js: 18.x nebo vyšší (doporučeno 20.x LTS)
  • pnpm: 10.29.2 nebo vyšší 
    npm install -g pnpm

Instalace

  1. Klonování repozitáře:

    git clone https://github.com/janszotkowski/vimzenicnevim.git
cd vimzenicnevim

  2. Instalace závislostí:

    pnpm install

    ⚠️ Poznámka: postinstall skripty jsou vypnuté (.npmrc: ignore-scripts=true). Pokud něco nefunguje, zkontrolujte, zda nepoužíváte balíček vyžadující build step.

  3. Environment Variables (volitelné): Vytvořte .env.local soubor pro Sentry integraci:

    SENTRY_DSN=your-sentry-dsn
SENTRY_ENVIRONMENT=development

Development Workflow

Spuštění vývojového serveru:

pnpm run dev

Aplikace poběží na http://localhost:3000 s Hot Module Replacement (HMR).

Spuštění Storybooku:

pnpm run storybook

Storybook UI poběží na http://localhost:6006.

Linting:

pnpm run lint        # Kontrola
pnpm run lint:fix    # Automatická oprava

Testing:

pnpm run test         # Spustí všechny testy
pnpm run test:watch   # Watch mode pro TDD

Build pro produkci:

pnpm run build        # Vytvoří optimalizovaný build
pnpm run start        # Spustí produkční server
pnpm run preview      # Preview produkčního buildu

Storybook build:

pnpm run build-storybook  # Vytvoří statický Storybook export

📂 Struktura projektu

vimzenicnevim.cz/
├── .github/                    # GitHub-specific configs
│   ├── workflows/              # CI/CD pipelines (pokud existují)
│   ├── CODE_OF_CONDUCT.md      # Pravidla chování
│   ├── CONTRIBUTING.md         # Návod pro contributory
│   └── SECURITY.md             # Security policy
│
├── .storybook/                 # Storybook konfigurace
│   ├── main.ts                 # Storybook main config
│   ├── preview.ts              # Global decorators a parameters
│   └── test-runner.ts          # Vitest integration config
│
├── public/                     # Statické assety (serializované as-is)
│   ├── images/                 # Obrázky, loga
│   ├── fonts/                  # Custom fonts (pokud ne z CDN)
│   └── favicon.ico             # Favicon a meta images
│
├── src/
│   ├── components/             # React komponenty
│   │   ├── ui/                 # Reusable UI komponenty (Button, Card, etc.)
│   │   ├── layout/             # Layout komponenty (Header, Footer, Sidebar)
│   │   └── features/           # Feature-specific komponenty
│   │
│   ├── routes/                 # File-based routing (TanStack Router)
│   │   ├── __root.tsx          # Root layout (obaluje všechny stránky)
│   │   ├── index.tsx           # Homepage (/)
│   │   ├── blog/               # Blog routes
│   │   │   ├── index.tsx       # Blog listing (/blog)
│   │   │   └── $slug.tsx       # Article detail (/blog/[slug])
│   │   └── about.tsx           # About page (/about)
│   │
│   ├── content/                # Content files (MDX, JSON)
│   │   └── blog/               # Blog články v MDX formátu
│   │       ├── typescript-tips.mdx
│   │       └── react-performance.mdx
│   │
│   ├── styles/                 # CSS a styling
│   │   ├── app.css             # Globální styly + Tailwind imports
│   │   └── themes/             # Theme variables (pokud existují)
│   │
│   ├── utils/                  # Utility funkce
│   │   ├── seo.ts              # SEO helpers (meta tags, og:image)
│   │   ├── formatters.ts       # Date formatting, string utils
│   │   └── mdx.ts              # MDX parsing a processing
│   │
│   ├── hooks/                  # Custom React hooks (pokud existují)
│   ├── types/                  # TypeScript type definitions
│   ├── app.tsx                 # App entry point
│   └── router.tsx              # Router configuration
│
├── tests/                      # Test files (pokud ne v src/)
│   ├── unit/                   # Unit testy
│   ├── integration/            # Integration testy
│   └── e2e/                    # End-to-end Playwright testy
│
├── .npmrc                      # pnpm konfigurace (ignore-scripts=true)
├── eslint.config.js            # ESLint konfigurace
├── tailwind.config.ts          # Tailwind konfigurace
├── tsconfig.json               # TypeScript konfigurace
├── vite.config.ts              # Vite build konfigurace
├── vitest.config.ts            # Vitest test konfigurace
├── instrument.server.mjs       # Sentry instrumentace pro SSR
├── package.json                # Dependencies a scripts
├── pnpm-lock.yaml              # Lockfile
└── README.md                   # Tento soubor

Důležité soubory

  • instrument.server.mjs: Sentry instrumentace, která musí běžet před jakoukoli jinou logikou (proto --import flag v package.json scriptech)
  • app.tsx: Root komponenta aplikace s Error Boundaries a Sentry integrací
  • router.tsx: TanStack Router setup s definicí všech route
  • .npmrc: Konfigurace pnpm s ignore-scripts=true pro bezpečnost

🔐 Bezpečnostní Praktiky

  1. Supply Chain Security:

    • postinstall skripty vypnuté
    • Renovate Bot pro automatické updates
    • Pravidelné dependency audity

  2. Runtime Monitoring:

    • Sentry error tracking s alertingem
    • UptimeRobot pro monitoring dostupnosti
    • Performance metrics pro optimalizaci

  3. Code Quality:

    • TypeScript strict mode
    • ESLint s přísnou konfigurací
    • Automatické testy před deployem

🚀 Deployment

Aplikace je deployována na [platformě] (doplň dle skutečnosti) s následující konfigurací:

  • Build command: pnpm run build
  • Start command: pnpm run start (nebo node --import ./dist/server/instrument.server.mjs dist/server/index.mjs)
  • Environment variables: Sentry DSN, další secrets