immersive2/NEXT_MIGRATION_PLAN.md

Vite to Next.js Migration Plan

Goal

Migrate from Vite to Next.js App Router to get proper API route support, with minimal changes to existing code.

Configuration

• Router: App Router with 'use client' on all pages
• Rendering: CSR only (no SSR) - simplifies migration since BabylonJS can't SSR
• API Routes: Claude API now, structured for future expansion
• External Proxies: Keep sync/create-db/images as Next.js rewrites to deepdiagram.com

---

Phase 1: Setup (No Breaking Changes)

1.1 Install Next.js

npm install next

1.2 Create next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      { source: '/sync/:path*', destination: 'https://www.deepdiagram.com/sync/:path*' },
      { source: '/create-db', destination: 'https://www.deepdiagram.com/create-db' },
      { source: '/api/images', destination: 'https://www.deepdiagram.com/api/images' },
    ];
  },
  webpack: (config, { isServer }) => {
    config.experiments = { ...config.experiments, asyncWebAssembly: true };
    return config;
  },
};
module.exports = nextConfig;

1.3 Update tsconfig.json

Add path alias:

"baseUrl": ".",
"paths": { "@/*": ["./*"] }

---

Phase 2: Create New Files

2.1 src/react/providers.tsx (extract from webApp.tsx)

• Move Auth0Provider and FeatureProvider wrapping here
• Add 'use client' directive
• Handle window/document checks for SSR safety

2.2 app/layout.tsx

• Root layout with html/body tags
• Metadata (title, favicon from current index.html)
• Import global CSS

2.3 app/globals.css

@import '../src/react/styles.css';
@import '@mantine/core/styles.css';

2.4 app/api/claude/[...path]/route.ts

• POST handler that proxies to api.anthropic.com
• Injects ANTHROPIC_API_KEY from env
• Adds x-api-key and anthropic-version headers

2.5 Page files (all with 'use client')

Route	File	Component
/	app/page.tsx	About
/documentation	app/documentation/page.tsx	Documentation
/examples	app/examples/page.tsx	Examples
/pricing	app/pricing/page.tsx	Pricing
/db/[visibility]/[db]	app/db/[visibility]/[db]/page.tsx	VrExperience
404	app/not-found.tsx	NotFound

2.6 src/react/components/ProtectedPage.tsx

• Next.js version of route protection
• Uses useRouter from next/navigation for redirects

---

Phase 3: Modify Existing Files

3.1 src/react/pages/vrExperience.tsx

Changes:

• Remove useParams() from react-router-dom
• Accept visibility and db as props instead
• Replace useNavigate() with useRouter() from next/navigation

3.2 src/react/pageHeader.tsx

Changes:

• Replace import {Link} from "react-router-dom" with import Link from "next/link"
• Change to={item.href} to href={item.href} on Link components

3.3 src/react/marketing/about.tsx

Changes:

• Replace useNavigate() with useRouter() from next/navigation
• Change navigate('/path') to router.push('/path')

3.4 package.json

"scripts": {
  "dev": "next dev -p 3001",
  "build": "node versionBump.js && next build",
  "start": "next start -p 3001",
  "test": "vitest",
  "socket": "node server/server.js",
  "serverBuild": "cd server && tsc"
}

---

Phase 4: Delete Old Files

File	Reason
vite.config.ts	Replaced by next.config.js
index.html	Next.js generates HTML
src/webApp.ts	Entry point no longer needed
src/react/webRouter.tsx	Replaced by app/ routing
src/react/webApp.tsx	Logic moved to providers.tsx
src/react/components/ProtectedRoute.tsx	Replaced by ProtectedPage.tsx

---

Critical Files to Modify

• src/react/pages/vrExperience.tsx - useParams -> props
• src/react/pageHeader.tsx - react-router Link -> Next.js Link
• src/react/marketing/about.tsx - useNavigate -> useRouter
• src/react/webApp.tsx - extract to providers.tsx
• package.json - scripts update
• tsconfig.json - path aliases

---

Migration Order

1. Install next, create next.config.js
2. Update tsconfig.json
3. Create app/globals.css
4. Create src/react/providers.tsx
5. Create app/layout.tsx
6. Create app/api/claude/[...path]/route.ts
7. Create src/react/components/ProtectedPage.tsx
8. Modify vrExperience.tsx (accept props)
9. Create all app/*/page.tsx files
10. Modify pageHeader.tsx (Next.js Link)
11. Modify about.tsx (useRouter)
12. Update package.json scripts
13. Delete old files (vite.config.ts, index.html, webApp.ts, webRouter.tsx, webApp.tsx)
14. Test all routes

---

Notes

• Havok WASM: Move HavokPhysics.wasm to public/ folder
• react-router-dom: Can be removed from dependencies after migration
• vite devDependencies: Can be removed (vite, vite-plugin-cp)