Bulletproof React Auditor
Audits React/TypeScript codebases against Bulletproof React architecture with migration planning.
When to Use
Natural Language Triggers (semantic matching, not keywords):
- Questions about React project structure or organization
- Mentions of "bulletproof react" or feature-based architecture
- Requests to audit, review, or improve React codebase
- Planning migrations or refactoring React applications
- Seeking guidance on component patterns or folder structure
Use Cases:
- Setting up new React project structure
- Reorganizing existing flat codebase
- Auditing architecture against Bulletproof standards
- Planning migration to feature-based patterns
- Code review for structural anti-patterns
- Generating refactoring guidance and ADRs
Bulletproof Structure Target
src/
├── app/ # Routes, providers
├── components/ # Shared components ONLY
├── config/ # Global config
├── features/ # Feature modules (most code)
│ └── feature/
│ ├── api/
│ ├── components/
│ ├── hooks/
│ ├── stores/
│ └── types/
├── hooks/ # Shared hooks
├── lib/ # Third-party configs
├── stores/ # Global state
├── testing/ # Test utilities
├── types/ # Shared types
└── utils/ # Shared utilities
Audit Categories
| Category |
Key Checks |
| Structure |
Feature folders, cross-feature imports, boundaries |
| Components |
Size (<300 LOC), props (<10), composition |
| State |
Appropriate categories, localization, server cache |
| API Layer |
Centralized client, types, React Query/SWR |
| Testing |
Trophy (70/20/10), semantic queries, behavior |
| Styling |
Consistent approach, component library |
| Errors |
Boundaries, interceptors, tracking |
| Performance |
Code splitting, memoization, bundle size |
| Security |
JWT cookies, RBAC, XSS prevention |
| Standards |
ESLint, Prettier, TS strict, Husky |
Usage Examples
# Basic audit
Audit this React codebase using bulletproof-react-auditor.
# Structure focus
Run structure audit against Bulletproof React patterns.
# Migration plan
Generate migration plan to Bulletproof architecture.
# Custom scope
Audit focusing on structure, components, and state management.
Output Formats
- Markdown Report - ASCII diagrams, code examples
- JSON Report - Machine-readable for CI/CD
- Migration Plan - Roadmap with effort estimates
Priority Levels
| Priority |
Examples |
Timeline |
| P0 Critical |
Security vulns, breaking issues |
Immediate |
| P1 High |
Feature folder creation, reorg |
This sprint |
| P2 Medium |
State refactor, API layer |
Next quarter |
| P3 Low |
Styling, docs, polish |
Backlog |
Connor's Standards Enforced
- TypeScript strict mode (no
any)
- 80%+ test coverage
- Testing trophy: 70% integration, 20% unit, 10% E2E
- No console.log in production
- Semantic queries (getByRole preferred)
Best Practices
- Fix folder organization before component refactoring
- Extract features before other changes
- Maintain test coverage during migration
- Incremental migration, not all at once
- Document decisions with ADRs
Limitations
- Static analysis only
- Requires React 16.8+ (hooks)
- Best for SPA/SSG (Next.js differs)
- Large codebases need scoped analysis
Resources
References
See reference/ for:
- Complete Bulletproof principles guide
- Detailed audit criteria checklist
- Migration patterns and examples
- ADR templates
1---2name: bulletproof-react-auditor3description: Use PROACTIVELY when users ask about React project structure, Bulletproof React patterns, or need architecture guidance. Covers structure setup, codebase auditing, anti-pattern detection, and feature-based migration planning. Triggers on "bulletproof react", "React structure help", "organize React app", or "audit my architecture".4---5
6# Bulletproof React Auditor
7
8Audits React/TypeScript codebases against Bulletproof React architecture with migration planning.
9
10## When to Use
11
12**Natural Language Triggers** (semantic matching, not keywords):
13- Questions about React project structure or organization
14- Mentions of "bulletproof react" or feature-based architecture
15- Requests to audit, review, or improve React codebase
16- Planning migrations or refactoring React applications
17- Seeking guidance on component patterns or folder structure
18
19**Use Cases**:
20- Setting up new React project structure
21- Reorganizing existing flat codebase
22- Auditing architecture against Bulletproof standards
23- Planning migration to feature-based patterns
24- Code review for structural anti-patterns
25- Generating refactoring guidance and ADRs
26
27## Bulletproof Structure Target
28
29```
30src/
31├── app/ # Routes, providers
32├── components/ # Shared components ONLY
33├── config/ # Global config
34├── features/ # Feature modules (most code)
35│ └── feature/
36│ ├── api/
37│ ├── components/
38│ ├── hooks/
39│ ├── stores/
40│ └── types/
41├── hooks/ # Shared hooks
42├── lib/ # Third-party configs
43├── stores/ # Global state
44├── testing/ # Test utilities
45├── types/ # Shared types
46└── utils/ # Shared utilities
47```
48
49## Audit Categories
50
51| Category | Key Checks |
52|----------|------------|
53| Structure | Feature folders, cross-feature imports, boundaries |
54| Components | Size (<300 LOC), props (<10), composition |
55| State | Appropriate categories, localization, server cache |
56| API Layer | Centralized client, types, React Query/SWR |
57| Testing | Trophy (70/20/10), semantic queries, behavior |
58| Styling | Consistent approach, component library |
59| Errors | Boundaries, interceptors, tracking |
60| Performance | Code splitting, memoization, bundle size |
61| Security | JWT cookies, RBAC, XSS prevention |
62| Standards | ESLint, Prettier, TS strict, Husky |
63
64## Usage Examples
65
66```
67# Basic audit
68Audit this React codebase using bulletproof-react-auditor.
69
70# Structure focus
71Run structure audit against Bulletproof React patterns.
72
73# Migration plan
74Generate migration plan to Bulletproof architecture.
75
76# Custom scope
77Audit focusing on structure, components, and state management.
78```
79
80## Output Formats
81
821. **Markdown Report** - ASCII diagrams, code examples
832. **JSON Report** - Machine-readable for CI/CD
843. **Migration Plan** - Roadmap with effort estimates
85
86## Priority Levels
87
88| Priority | Examples | Timeline |
89|----------|----------|----------|
90| P0 Critical | Security vulns, breaking issues | Immediate |
91| P1 High | Feature folder creation, reorg | This sprint |
92| P2 Medium | State refactor, API layer | Next quarter |
93| P3 Low | Styling, docs, polish | Backlog |
94
95## Connor's Standards Enforced
96
97- TypeScript strict mode (no `any`)
98- 80%+ test coverage
99- Testing trophy: 70% integration, 20% unit, 10% E2E
100- No console.log in production
101- Semantic queries (getByRole preferred)
102
103## Best Practices
104
1051. Fix folder organization before component refactoring
1062. Extract features before other changes
1073. Maintain test coverage during migration
1084. Incremental migration, not all at once
1095. Document decisions with ADRs
110
111## Limitations
112
113- Static analysis only
114- Requires React 16.8+ (hooks)
115- Best for SPA/SSG (Next.js differs)
116- Large codebases need scoped analysis
117
118## Resources
119
120- [Bulletproof React Guide](https://github.com/alan2207/bulletproof-react)
121- [Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)
122- [Sample App](https://github.com/alan2207/bulletproof-react/tree/master/apps/react-vite)
123
124## References
125
126See `reference/` for:
127- Complete Bulletproof principles guide
128- Detailed audit criteria checklist
129- Migration patterns and examples
130- ADR templates
majiayu000