| name | bulletproof-react-auditor |
| description | 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". |
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
