# Migration Notes — Vite/React-Router → Next.js (App Router)

The original codebase was a Vite + React 18 + React Router v7 prototype
focused exclusively on UI/UX. This document records what changed in the
refactor and what still has rough edges.

## What changed

| Concern                | Before                                  | After                                              |
| ---------------------- | --------------------------------------- | -------------------------------------------------- |
| Framework              | Vite 6                                  | Next.js 15 (App Router)                            |
| React                  | 18.3.1                                  | 19.x                                               |
| Routing                | `react-router` v7 (`createBrowserRouter`) | Next App Router file-system routes                |
| Layout primitives      | `<Outlet />`                            | `children` prop on layouts                         |
| Image                  | `import logo from '../imports/logo.png'` | Static file at `/images/logo.png` (or `next/image`) |
| Styling entry point    | `src/styles/index.css` via `main.tsx`   | `src/app/globals.css` via root layout              |
| Tailwind scan          | `@source '../**'`                       | Explicit `@source` per top folder                  |
| Folder structure       | `src/app/{components,pages,admin}`      | `src/{app,features,shared}` (FSD)                  |
| State                  | Local component state only              | Zustand stores per feature                         |
| Data layer             | None — UI was static                    | Service files + dummy fallback wrapper             |

## Compatibility shim

`src/shared/lib/router-compat.tsx` provides `Link`, `NavLink`, `useLocation`,
`useNavigate`, `useParams`, `useSearchParams`, `Outlet`, `ScrollRestoration`
that delegate to `next/link` and `next/navigation`. This means most page
components could be moved without rewriting their JSX.

`<Link to="/x">` still works because the shim accepts the legacy `to` prop
and forwards it as `href`.

> **Future cleanup:** new code should import directly from `next/link` /
> `next/navigation`. Once we audit every page, the shim and its imports can
> be deleted in a single commit.

## What was deleted

* `vite.config.ts`, `index.html`, `pnpm-workspace.yaml`, `vercel.json`,
  `default_shadcn_theme.css`, `package-lock.json`
* `src/main.tsx`, `src/app/App.tsx`, `src/app/routes.tsx`
* The `src/imports/` folder (logo moved to `public/images/`)
* All non-logo screencapture PNGs (they were Figma-export references and not
  used at runtime)

## Known follow-ups

* **Auth UI** – the auth feature has a store and service, but no `(auth)`
  route group or login page yet. Wire up
  `src/app/(auth)/login/page.tsx` when the backend `POST /auth/login` is
  ready.
* **Server Components** – many pages that don't need interactivity are still
  `'use client'` because they were ported wholesale. Identify pure-presentational
  pages and demote them to RSC for SSR/SEO benefits.
* **`next/image`** – the marketing pages still use `<img>` tags inherited
  from the prototype. Swap to `next/image` for automatic responsive
  optimisation.
* **MUI bundle size** – consider dropping MUI in favour of shadcn-only.
  Currently both are imported, doubling the styled-component runtime cost.
* **Image domains** – `next.config.ts` whitelists `images.unsplash.com` and
  `cdn.dolphinjapan.com`. Add real CDN domains as the backend uploads media.
* **Locales/currency** – the existing UI shows English/USD selectors but
  has no i18n layer; integrate `next-intl` or a similar library when needed.

## Required actions after pulling

```bash
# Old node_modules will not work — toolchain has changed.
rm -rf node_modules package-lock.json pnpm-lock.yaml
npm install
cp .env.local.example .env.local
npm run dev
```