---
title: alan2207/bulletproof-react — Audit
type: audit
tags: [architecture-audit, kar-522, react, architecture, best-practices, opinionated]
date: 2026-05-22
status: aktiv
source: https://github.com/alan2207/bulletproof-react
prioritaet: hoch
nutzen: BESTE Real-World-React-Architektur-Guide 2026. Production-Ready Patterns. Decken Source 2 (Clean Arch) + Source 4 (FSD) + Source 10 (React.dev) in einer praktischen Demo. Direkt fuer Kadi-v2 anwendbar.
thema: Architecture, React, Production-Patterns
related: ["[[00-plan]]", "[[02-clean-architecture-uncle-bob]]", "[[04-feature-sliced-design]]", "[[10-react-dev]]"]
linear: KAR-522
confidence: high
---

# alan2207/bulletproof-react — Audit

> Source: https://github.com/alan2207/bulletproof-react — Alan Alickovic, MIT.
> Audited 2026-05-22 als Source 14/20 von KAR-522. Strenge Bewertung.

## 1. Kernidee

Bulletproof-React ist ein **opinionated Architecture-Guide + Sample-Apps** fuer Production-Ready React-Anwendungen. Anders als die anderen "Web-App-Skeletons" (Sources 12, 13) ist es **kein Template** sondern eine **Doku + Demo-App** in 3 Stack-Varianten (Next.js App Router, Next.js Pages Router, React + Vite).

Disclaimer im README: *"This is not supposed to be a template, boilerplate or a framework. It is an opinionated guide..."* — wichtig fuer richtige Adoption.

**12-Doku-Sektionen** (jede ist Adoption-Wert):

| Sektion | Inhalt |
|---------|--------|
| Application Overview | Stack-Wahl |
| Project Standards | ESLint, TypeScript, Prettier, Husky |
| Project Structure | Folder-Layout + Cross-Import-Rules |
| Components and Styling | Composition, Variants, Tailwind/CSS-Modules |
| API Layer | Axios + React-Query Pattern |
| State Management | 5 Kategorien (Component, Application, Server-Cache, Form, URL) |
| Testing | Vitest + RTL + MSW + Playwright |
| Error Handling | Boundaries + Toasts + API-Errors |
| Security | Auth, RBAC, XSS, CSRF |
| Performance | Bundle, Memo, Code-Split, Image-Opt |
| Deployment | knapp, generisch |
| Additional Resources | weiterfuehrende Links |

**Project-Structure-Empfehlung** (entspricht FSD-light, Source 4):

```
src/
├── app/         # Routes + global Provider + Router
├── assets/      # static
├── components/  # shared (UI-Kit)
├── config/      # env-vars
├── features/    # Feature-Module (mit api/, components/, hooks/, stores/, types/, utils/)
├── hooks/       # shared
├── lib/         # preconfigured Libraries
├── stores/      # global state
├── testing/     # test utils + mocks
├── types/       # shared types
└── utils/       # shared utils
```

**Cross-Feature-Imports verboten** via ESLint `import/no-restricted-paths`. **Unidirectional codebase**: `shared → features → app`.

**State-Management-Klassifikation** (5 Kategorien, explizit):

| Typ | Tool |
|-----|------|
| Component State | `useState`, `useReducer` |
| Application State | Context+Hooks, Zustand, Jotai, Redux-Toolkit, MobX, xState |
| Server Cache | TanStack Query, SWR, Apollo, urql, RTK Query |
| Form State | React-Hook-Form, Formik, Final Form (+ Zod fuer Validierung) |
| URL State | react-router params/query |

## 2. Was uebernehmen

### Kadi-v2 (HOECHSTE RELEVANZ)

**Direkt adopten:**

1. **Folder-Structure** wie oben — `app/`, `features/`, `components/`, `hooks/`, `lib/`, `config/`, `utils/`, `types/`. Mapping auf Next.js App-Router:
   - `app/` ist Next.js Route-Folder
   - `src/features/` parallel dazu
   - shared in `src/{components,hooks,lib,utils,types,config}/`
2. **Cross-Feature-Import-Restrictions** via ESLint:
   ```js
   'import/no-restricted-paths': [
     'error',
     {
       zones: [
         { target: './src/features/auth', from: './src/features', except: ['./auth'] },
         { target: './src/features/evaluations', from: './src/features', except: ['./evaluations'] },
         // pro Feature eine Zone
       ]
     }
   ]
   ```
3. **Unidirectional Codebase** via ESLint:
   ```js
   { target: './src/features', from: './src/app' },  // features != import from app
   { target: ['./src/components', './src/hooks', './src/lib', './src/types', './src/utils'],
     from: ['./src/features', './src/app'] }  // shared != import from features/app
   ```
4. **State-Management-Klassifikation** als ADR:
   - Component → `useState`
   - Server-Cache → TanStack Query (oder Next.js Server-Components, was wir nutzen)
   - Form → React-Hook-Form + Zod
   - Application → Zustand (klein und elegant)
   - URL → Next.js useSearchParams/Params
5. **Form-Pattern** — Abstract `Form`-Component + Input-Felder die React-Hook-Form-API wrappen. Konsistent UX.
6. **No Barrel-Files** — laut Doku: Barrel-Files brechen Vite-Tree-Shaking. Direkt importieren statt index.ts. **Aenderung zu vorherigem FSD-Audit-Vorschlag — bulletproof-react ueberstimmt.**
7. **Testing-Stack**: Vitest + React Testing Library + MSW (Mock-Service-Worker) + Playwright. Standard fuer Production-React.
8. **Pre-commit-Hooks via Husky**: lint, format, type-check vor jedem Commit.

### Aria

**Limited applicability** (Aria ist Bash/Python, kein React). Aber:

- **State-Klassifikation** als Mental-Model fuer Aria-Daten:
  - Skill-Internal-State = Component State
  - Brain-Vault = Server-Cache-Equivalent
  - Mode/Identity = Application State
  - Telegram-Chat-ID = URL/Session State

## 3. Was NICHT uebernehmen

1. **Sample-App-Code direkt kopieren** — Disclaimer sagt's selbst: "not a template". Pattern verstehen, eigenen Code schreiben.
2. **Axios + React-Query** — fuer Kadi-v2 mit Next.js Server-Components ist Server-Side-Data-Fetching der Default. React-Query nur fuer Client-Side-Mutations oder Reactive-Data.
3. **react-router** — Next.js bringt eigenen File-System-Router. react-router nur fuer React + Vite Variante.
4. **Husky-Pre-commit-Hooks ueberzogen** — Lint + Format vor jedem Commit OK, aber Type-Check + Tests pre-commit kann langsam werden. Wir setzen das in CI, Husky nur fuer schnelle Checks.
5. **5 verschiedene State-Tools** — wir entscheiden uns fuer EINEN Application-State-Tool (Zustand) und EINEN Server-Cache-Approach (Server Components + selective React-Query). Keine 5-Tool-Soup.

## 4. Kritik / Schwaechen

> Strenge Bewertung. Bulletproof-React ist excellent — hier die Schwaechen.

### Inhaltlich

1. **Multi-Stack-Maintenance** — Repo hat 3 Sample-Apps (Next App, Next Pages, React+Vite). Pflege ungleich. Next-Pages-Beispiel veraltet schnell. Newcomer verwirrt welche Variante zu nehmen.
2. **Server-Components-Story dünn** — App-Router-Variante existiert, aber Doku schreibt noch viele Client-Side-Pattern (axios + react-query). Hybrid-Stack erklaert nicht klar.
3. **Form-Pattern erfordert Custom-Abstraction** — Abstract Form-Component zu bauen ist Aufwand. Fuer Solo-Dev-Projekte oft over-engineered. Direkter React-Hook-Form-Use ist auch OK.
4. **Cross-Feature-Imports via ESLint-Zones** ist Konfig-Geheul — jede neue Feature braucht neuen Zone-Eintrag. Skaliert nicht elegant. Plugin wie `eslint-plugin-boundaries` waere besser.
5. **State-Management-Sektion listet 6 Tools ohne Empfehlung** — "use any of these". Newcomer braucht Empfehlung. "Default: Zustand fuer kleine Apps, Redux-Toolkit fuer grosse" waere besser.
6. **Security-Sektion thin** — 4.7 KB Doku-File. ASVS-Vergleich (Source 6) zeigt: 280 Reqs fuer L2. Bulletproof-React reduziert das auf 5 Tipps. Underdosed.
7. **Performance-Sektion gut, aber static** — Performance-Best-Practices aktualisieren sich schnell (React 19 Compiler, RSC, Suspense). Doku-Updates lag-y.
8. **Deployment-Sektion ist 307 Bytes** — "deploy on Vercel". Anti-12-Factor-Adherence. Sollte mehr sein.
9. **No Observability** — kein OpenTelemetry, Sentry, Datadog. Modern Production-React braucht das.
10. **No Internationalization** — i18n-Pattern fehlt komplett. Bei mehrsprachigen Apps gross Luecke.

### Strukturell

11. **GitHub-Stars-Trap** — Bulletproof-React hat 25k+ Stars. Quality + Aktualitaet folgen nicht automatisch aus Popularitaet. Trotz Stars: manche Pattern sind 2022-Era (vor RSC).
12. **Author-Solo-Maintenance** — Alan Alickovic alleine. Wenn er busy ist, Repo veraltet. Risiko fuer Adoption-Story.
13. **AGENTS.md** (8.9 KB!) — eigene Datei fuer AI-Coding-Agents. Spannend, dass das jetzt First-Class ist. Pruefen ob's Aria-relevant ist.
14. **No Mobile-Story** — Repo ist Web. React-Native-Equivalent (bulletproof-react-native?) fehlt.

### Konzeptionell

15. **Anti-Barrel-File-Stance kontrovers** — Tree-Shaking-Argument stimmt fuer Vite, aber bei Next.js webpack-build ist's anders. Manche Teams haben Barrels und's funktioniert. Nicht Schwarz-Weiss.
16. **Disclaimer "nicht Template" wird ignoriert** — User clonen das Repo trotzdem und behandeln's als Boilerplate. Adoption-Pattern ist gegen Author-Intent.

### Verdict

Bulletproof-React ist **die beste Real-World-React-Architektur-Doku 2026**. Source 2 (Clean Arch) + Source 4 (FSD) + Source 10 (React.dev) werden hier in einer praktischen Form vereint. **Kadi-v2 sollte einen "Bulletproof-React-konformes Refactor" als Ziel haben**, anstatt 3 separate Refactors aus Clean/FSD/React-Docs.

## 5. Action-Items fuer Kadi-v2

| # | Action | KAR-Issue | Effort | Priority | Reason |
|---|--------|-----------|--------|----------|--------|
| K1 | Folder-Structure-Refactor (bulletproof-react-konform): app/, features/, components/, lib/, ... | NEU | M | P2 | Konsolidiert FSD-Audit-Action (K2 von Source 4) |
| K2 | ESLint `import/no-restricted-paths` mit Cross-Feature + Unidirectional Rules | NEU | M | P2 | Erzwingt Boundaries |
| K3 | State-Management-ADR mit 5 Kategorien + Tool-Empfehlung pro Kategorie | NEU | S | P2 | Konsolidiert Source 10 (React.dev) Action |
| K4 | Form-Pattern: React-Hook-Form + Zod, abstrakte Form-Component | NEU | M | P2 | UX-Konsistenz bei BMW-Forms |
| K5 | Testing-Stack einrichten: Vitest + RTL + MSW + Playwright | NEU | L | P2 | Production-Bar fuer BMW-Pilot |
| K6 | Husky-Pre-commit fuer Lint+Format (nicht Type-Check, das in CI) | NEU | S | P2 | Code-Quality-Baseline |
| K7 | API-Layer-ADR — Server-Components-First, React-Query fuer Reactive-Cases | NEU | S | P3 | Konsolidiert API-Pattern |

## 6. Action-Items fuer Aria

| # | Action | KAR-Issue | Effort | Priority | Reason |
|---|--------|-----------|--------|----------|--------|
| A1 | Bulletproof-React `AGENTS.md` lesen + Aria-Equivalent erwaegen | NEU | S | P3 | Aria=Coding-Agent, vielleicht direkt anwendbar |
| A2 | Bei Aria-Distribution-Web-UI: bulletproof-react als Foundation | NEU | M | P4 | Bei Build, nicht jetzt |

## 7. Future-Project-Relevanz

- **Aria-Distribution Web-UI**: Bulletproof-React-Stack-Defaults adoptieren = Best-Practice ab Tag 1.
- **Future Side-Projects mit React**: Bulletproof-React als Reference, eigene "Bulletproof-Aria-Style"-Doku ableiten.
- **Standing-Order-Kandidat**:
  - "Jedes neue React-Projekt: Bulletproof-React-konforme Folder-Structure + ESLint-Boundaries + Testing-Stack ab Tag 1."

## Cross-References zu anderen Audit-Sources

- **Source 2 (Clean Architecture)**: bulletproof-react ist praktische Clean-Arch fuer React.
- **Source 4 (Feature-Sliced Design)**: bulletproof-react ist FSD-light fuer React (4 Layer statt 6).
- **Source 6 (OWASP ASVS)**: Security-Sektion ist thin — ASVS ist tiefergehend.
- **Source 9 (Next.js)**: bulletproof-react App-Router-Variante zeigt Konvention.
- **Source 10 (React.dev)**: bulletproof-react ist die praktische Doku, React.dev ist theoretisch.

---

**Status**: Source 14/20 complete. Nachfolger: Source 15 — ixartz/Next-js-Boilerplate.