ALwrity/.planning/STATE.md

Project State: Alwrity

Current Position

Active Phase: Phase 1 - Code Splitting & Feature-Based Lazy Loading
Phase Status: ✅ Complete — Ready for Phase 2
Milestone: v1.0 - Frontend Optimization

Phase Progress

Phase 1: Code Splitting & Feature-Based Lazy Loading

• Status: ✅ Complete
• Plans: 3 plans executed (01-01, 01-02, 01-03)

Plans:

• 01-01: Convert 31 static imports to React.lazy with Suspense
• 01-02: Add feature-gated route loading using ALWRITY_ENABLED_FEATURES
• 01-03: Convert MUI icon barrel imports to individual imports (111 files)

Results:

• Main bundle: 8.42MB → 2.50MB (70% reduction via React.lazy)
• 190+ chunk files for route-level code splitting
• 47 routes feature-gated with ALWRITY_ENABLED_FEATURES
• 16 feature keys in FEATURE_KEYS constant
• 111 files converted from barrel to individual MUI icon imports
• Zero barrel imports from @mui/icons-material remain

Phase 2: Migrate CRA to Vite

• Status: Ready to start (Phase 1 complete)
• Plans: 3 plans created (02-01, 02-02, 02-03)
• Dependencies: Phase 1 complete

Plans:

• 02-01: Install Vite dependencies and create configuration
• 02-02: Migrate index.html and entry point
• 02-03: Update environment variables and scripts

Phase 3: Production Validation (Planned)

• Depends on: Phase 2
• Focus: Vercel deploy, full feature testing

Phase 4: (Removed — MUI icon optimization folded into Phase 1-03)

Decisions Made

Locked Decisions

• Code splitting first, then Vite migration (not the other way around) ✅ Done
• Use React.lazy for ALL route components (this is a React feature, NOT bundler-specific) ✅ Done
• Use ALWRITY_ENABLED_FEATURES for feature-gated route loading ✅ Done
• MUI icon imports before Vite migration — barrel imports converted to individual per-file default imports ✅ Done
• Use Vite 5.x with @vitejs/plugin-react
• Disable sourcemaps in production build for speed
• Migrate env vars from REACT_APP_* to VITE_*

Patterns Established

• MUI icon imports: Always import IconName from '@mui/icons-material/IconName' — never barrel destructuring
• Route splitting: All route components use React.lazy with Suspense
• Feature gating: FeatureRoute wraps inside ProtectedRoute (auth → then feature check)

Key Insight

React.lazy is a React feature (not CRA or Vite specific). Doing code splitting first with CRA:

1. Immediately reduces main bundle from 8.42MB → ~1-2MB
2. Adds no risk (React.lazy is stable since React 16.6)
3. Makes Vite migration smoother (bundles are already split)
4. ALWRITY_ENABLED_FEATURES can prevent disabled feature bundles from loading at all

MUI icon barrel imports eliminated — 111 files converted to individual per-file imports. This ensures reliable tree-shaking during Vite migration and beyond.

---

Last updated: 2026-05-08 Updated by: gsd-executor