mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 22:34:56 +00:00
168 lines
4.6 KiB
Markdown
168 lines
4.6 KiB
Markdown
# Next.js Migration Guide
|
|
|
|
## Overview
|
|
Complete migration from Vite SPA to Next.js 15 App Router while maintaining all existing functionality.
|
|
|
|
## Migration Strategy
|
|
|
|
### Phase 1: Setup ✅
|
|
- [x] Install Next.js 15.1.6 and React 19
|
|
- [x] Install Next.js dependencies (@next/third-parties, sharp)
|
|
- [ ] Create next.config.ts
|
|
- [ ] Create App Router structure
|
|
- [ ] Migrate environment variables
|
|
|
|
### Phase 2: Core Structure (In Progress)
|
|
- [ ] Convert App.tsx to root layout + page structure
|
|
- [ ] Setup authentication middleware
|
|
- [ ] Create nested layouts for each level
|
|
- [ ] Implement file-based routing
|
|
- [ ] Migrate DBAL integration to Next.js
|
|
|
|
### Phase 3: Component Migration
|
|
- [ ] Convert Level components to route pages
|
|
- [ ] Setup Server Components (public pages)
|
|
- [ ] Setup Client Components (interactive features)
|
|
- [ ] Migrate shadcn/ui components
|
|
- [ ] Update imports and paths
|
|
|
|
### Phase 4: Features
|
|
- [ ] Implement API routes for DBAL operations
|
|
- [ ] Setup server actions for auth
|
|
- [ ] Add SSR/SSG for public pages
|
|
- [ ] Implement middleware for auth protection
|
|
- [ ] Image optimization with next/image
|
|
- [ ] Font optimization
|
|
|
|
### Phase 5: Docker & Deployment
|
|
- [ ] Update Dockerfile for Next.js standalone
|
|
- [ ] Update docker-compose files
|
|
- [ ] Test production build
|
|
- [ ] Update CI/CD workflows
|
|
|
|
## File Structure
|
|
|
|
```
|
|
app/
|
|
├── layout.tsx # Root layout with providers
|
|
├── page.tsx # Level 1 (public home)
|
|
├── login/
|
|
│ └── page.tsx # Login/Register page
|
|
├── (auth)/ # Auth-protected routes
|
|
│ ├── layout.tsx # Auth layout with user context
|
|
│ ├── dashboard/ # Level 2 - User area
|
|
│ │ └── page.tsx
|
|
│ ├── admin/ # Level 3 - Admin panel
|
|
│ │ └── page.tsx
|
|
│ ├── builder/ # Level 4 - God mode
|
|
│ │ └── page.tsx
|
|
│ └── supergod/ # Level 5 - Supergod mode
|
|
│ └── page.tsx
|
|
├── api/ # API routes
|
|
│ ├── auth/
|
|
│ │ ├── login/route.ts
|
|
│ │ ├── register/route.ts
|
|
│ │ └── logout/route.ts
|
|
│ └── dbal/
|
|
│ └── [...path]/route.ts # DBAL proxy routes
|
|
└── _components/ # Shared components (not routes)
|
|
```
|
|
|
|
## Key Decisions
|
|
|
|
### Server vs Client Components
|
|
- **Server Components** (default):
|
|
- Level 1 (public landing)
|
|
- Static content
|
|
- Layout shells
|
|
|
|
- **Client Components** ("use client"):
|
|
- Level 2-5 (require interactivity)
|
|
- Forms and inputs
|
|
- State management
|
|
- DBAL operations
|
|
- Canvas/editor components
|
|
|
|
### Routing Strategy
|
|
- File-based routing with App Router
|
|
- Route groups `(auth)` for protected routes
|
|
- Middleware for authentication checks
|
|
- Dynamic routes for user-specific pages
|
|
|
|
### State Management
|
|
- Server state: Server components + server actions
|
|
- Client state: React Context + hooks (existing)
|
|
- Form state: React Hook Form (existing)
|
|
- Async state: TanStack Query (existing)
|
|
|
|
### DBAL Integration
|
|
- Keep existing TypeScript DBAL client
|
|
- API routes proxy to C++ daemon
|
|
- Client components use DBAL hooks
|
|
- Server components use direct Prisma
|
|
|
|
## Benefits of Next.js
|
|
|
|
1. **Performance**:
|
|
- Server-side rendering for faster initial load
|
|
- Automatic code splitting
|
|
- Image optimization
|
|
- Font optimization
|
|
|
|
2. **SEO**:
|
|
- Server-rendered pages
|
|
- Dynamic meta tags
|
|
- Sitemap generation
|
|
|
|
3. **Developer Experience**:
|
|
- File-based routing
|
|
- Built-in API routes
|
|
- TypeScript support
|
|
- Fast Refresh
|
|
|
|
4. **Production**:
|
|
- Optimized builds
|
|
- Edge runtime support
|
|
- Middleware for auth
|
|
- Better error handling
|
|
|
|
## Compatibility
|
|
|
|
### Preserved Features
|
|
- ✅ All 5 levels functionality
|
|
- ✅ Authentication system
|
|
- ✅ DBAL integration
|
|
- ✅ Prisma database
|
|
- ✅ Shadcn/ui components
|
|
- ✅ Tailwind CSS
|
|
- ✅ Docker deployment
|
|
- ✅ Multi-tenant support
|
|
- ✅ All existing hooks and utilities
|
|
|
|
### New Capabilities
|
|
- ✅ SSR for public pages
|
|
- ✅ API routes
|
|
- ✅ Middleware auth
|
|
- ✅ Image optimization
|
|
- ✅ Incremental Static Regeneration (ISR)
|
|
|
|
## Testing Strategy
|
|
|
|
1. **Development**: Test each level after migration
|
|
2. **Build**: Ensure production build works
|
|
3. **E2E**: Run existing Playwright tests
|
|
4. **Docker**: Verify container deployment
|
|
5. **Performance**: Compare bundle sizes and load times
|
|
|
|
## Rollback Plan
|
|
|
|
Git tags mark each phase - can rollback to any phase if issues arise.
|
|
|
|
## Progress Tracking
|
|
|
|
- Phase 1: ✅ Complete
|
|
- Phase 2: 🔄 In Progress
|
|
- Phase 3: ⏳ Pending
|
|
- Phase 4: ⏳ Pending
|
|
- Phase 5: ⏳ Pending
|