docs: add project research
This commit is contained in:
@@ -0,0 +1,230 @@
|
||||
# Architecture Patterns
|
||||
|
||||
**Project:** Portfolio Killian Dalcin — Nuxt 4 SSR Migration
|
||||
**Researched:** 2026-04-07
|
||||
**Confidence:** HIGH (based on official Nuxt 4 conventions + existing codebase analysis)
|
||||
|
||||
---
|
||||
|
||||
## Recommended Architecture
|
||||
|
||||
```
|
||||
[ Browser ]
|
||||
|
|
||||
| HTTP request (SSR-rendered HTML on first load)
|
||||
v
|
||||
[ Nuxt 4 Server (Node 22) ]
|
||||
|
|
||||
|-- [ app/ ]
|
||||
| |-- [ pages/ ] File-based routing
|
||||
| |-- [ components/ ] Auto-imported UI components
|
||||
| |-- [ composables/ ] Auto-imported reactive logic
|
||||
| |-- [ layouts/ ] default.vue (header + footer)
|
||||
| |-- [ assets/ ] Static assets (images, fonts)
|
||||
| |-- [ plugins/ ] EmailJS init, gtag init
|
||||
|
|
||||
|-- [ server/ ]
|
||||
| |-- (optional) api/ Not needed — no dynamic data
|
||||
|
|
||||
|-- [ data/ ] Static TS files (projects, testimonials, FAQ, techstack)
|
||||
|
|
||||
|-- nuxt.config.ts Modules, runtime config, i18n, color-mode
|
||||
```
|
||||
|
||||
Nuxt 4 uses `app/` as the root source directory (replaces Nuxt 3's flat root layout). All pages, components, composables, layouts, and plugins live under `app/`.
|
||||
|
||||
---
|
||||
|
||||
## Component Boundaries
|
||||
|
||||
| Component | Responsibility | Communicates With |
|
||||
|-----------|---------------|-------------------|
|
||||
| `layouts/default.vue` | Shell: TheHeader + TheFooter + `<slot />` | All pages via slot |
|
||||
| `TheHeader.vue` | Navigation + locale toggle + color-mode toggle | `useI18n()`, `useColorMode()` |
|
||||
| `TheFooter.vue` | Links, copyright, social | `useI18n()` |
|
||||
| `pages/index.vue` | Hero + featured projects + services + CTA | `useProjects()`, `useSeoMeta()` |
|
||||
| `pages/projects.vue` | Project list + filters | `useProjects()` |
|
||||
| `pages/project/[id].vue` | Project detail + image gallery modal | `useProjects()`, `UModal` (Nuxt UI) |
|
||||
| `pages/about.vue` | Bio, tech stack | `useI18n()`, static `techstack.ts` |
|
||||
| `pages/contact.vue` | UForm + EmailJS send | `useContactForm()`, EmailJS plugin |
|
||||
| `pages/fiverr.vue` | Fiverr landing, service cards | `useI18n()`, static config |
|
||||
| `pages/formation.vue` | Training/course landing | `useI18n()` |
|
||||
| `components/ProjectCard.vue` | Reusable card (list + featured) | Props only, no store |
|
||||
| `components/GalleryModal.vue` | UModal wrapper for project images | Emits only, props: images[] |
|
||||
| `composables/useProjects.ts` | Filter/search logic over static data | Imports `data/projects.ts` |
|
||||
| `composables/useSeoMeta.ts` | Per-route `useSeoMeta()` + JSON-LD | Nuxt built-in `useSeoMeta` |
|
||||
| `data/*.ts` | Static typed data — single source of truth | Imported by composables only |
|
||||
|
||||
**Rule:** Pages import composables. Composables import data files. Components receive props and emit events. No page imports another page. No component imports data files directly.
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
data/projects.ts (static TS, bilingual strings)
|
||||
|
|
||||
v
|
||||
composables/useProjects.ts
|
||||
- filter by category
|
||||
- find by id
|
||||
- expose featuredProjects, allProjects
|
||||
|
|
||||
v
|
||||
pages/index.vue → featuredProjects → <ProjectCard />
|
||||
pages/projects.vue → allProjects + filters → <ProjectCard />
|
||||
pages/project/[id].vue → findById(route.params.id) → detail view + <GalleryModal />
|
||||
```
|
||||
|
||||
```
|
||||
i18n locale (cookie, SSR-safe)
|
||||
|
|
||||
v
|
||||
@nuxtjs/i18n module (strategy: 'prefix_except_default', defaultLocale: 'fr')
|
||||
- /fr/* and /* (default) both work
|
||||
- /en/* for English
|
||||
|
|
||||
v
|
||||
All pages and composables via useI18n() (auto-imported by @nuxtjs/i18n)
|
||||
```
|
||||
|
||||
```
|
||||
Color mode (cookie, SSR-safe)
|
||||
|
|
||||
v
|
||||
@nuxtjs/color-mode (cookie strategy, no FOUC)
|
||||
|
|
||||
v
|
||||
TheHeader.vue toggle → Tailwind dark: classes respond immediately
|
||||
```
|
||||
|
||||
```
|
||||
Contact form
|
||||
|
|
||||
v
|
||||
pages/contact.vue → UForm validation → composables/useContactForm.ts
|
||||
|
|
||||
v
|
||||
EmailJS plugin (client-side send, no server route needed)
|
||||
```
|
||||
|
||||
```
|
||||
SEO per route
|
||||
|
|
||||
v
|
||||
Each page calls useSeoMeta() with i18n-translated values
|
||||
+ JSON-LD script tag on pages/index.vue only
|
||||
|
|
||||
v
|
||||
@nuxtjs/sitemap generates sitemap.xml from route list at build time
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## i18n Architecture Decision
|
||||
|
||||
Use `@nuxtjs/i18n` v9 with `strategy: 'prefix_except_default'`:
|
||||
- French (`fr`) is default, served at `/`, `/projects`, `/project/[id]`, etc.
|
||||
- English served at `/en`, `/en/projects`, `/en/project/[id]`, etc.
|
||||
- Locale detected from browser `Accept-Language` header on first visit (server-side), then persisted in cookie.
|
||||
- **No redirect strategy** — prefix_except_default avoids redirect chains that hurt Core Web Vitals.
|
||||
- Translation strings live in `app/i18n/locales/fr.ts` and `app/i18n/locales/en.ts` (migrated from existing `src/locales/`).
|
||||
|
||||
The existing `useI18n.ts` composable wrapping vue-i18n is replaced entirely by the `useI18n()` auto-import provided by `@nuxtjs/i18n`.
|
||||
|
||||
---
|
||||
|
||||
## Static Data Layer
|
||||
|
||||
Decision: static TS files in `data/` (not `@nuxt/content`, not `server/api`).
|
||||
|
||||
Rationale:
|
||||
- All project data is known at build time and changes infrequently.
|
||||
- `@nuxt/content` adds markdown parsing overhead and a file-system watcher not needed for typed data.
|
||||
- `server/api` routes add network round-trips and cold-start latency for data that never changes.
|
||||
- Static TS files are tree-shakeable, fully typed, and zero-overhead.
|
||||
|
||||
Migration from `src/data/` is direct: copy files to `data/`, ensure bilingual structure is preserved (FR/EN fields in same object, selected by locale in composables).
|
||||
|
||||
---
|
||||
|
||||
## Deployment: SSR vs SSG
|
||||
|
||||
**Recommendation: `nuxt build` (SSR) not `nuxt generate` (SSG).**
|
||||
|
||||
Rationale:
|
||||
- i18n with cookie-based locale detection requires server execution to read the cookie and render the correct language on first request. SSG pre-renders all routes in one language only.
|
||||
- `useSeoMeta()` with i18n-reactive values requires server-side execution per request.
|
||||
- The Docker image runs `node server/index.mjs` (the Nuxt nitro server) — not nginx serving static files.
|
||||
- SSR does not meaningfully increase operational complexity for a portfolio (low traffic, single container).
|
||||
|
||||
Dockerfile pattern: multi-stage — build stage (`node:22-alpine` + `nuxt build`), production stage (copy `.output/` only, `CMD ["node", ".output/server/index.mjs"]`). No nginx layer needed.
|
||||
|
||||
---
|
||||
|
||||
## Suggested Build Order (Phase Dependencies)
|
||||
|
||||
```
|
||||
1. nuxt.config.ts + nuxt.config modules
|
||||
Depends on: nothing
|
||||
Blocks: everything — module config must exist before page/component work
|
||||
|
||||
2. data/ migration (static TS files)
|
||||
Depends on: nothing
|
||||
Blocks: composables, all pages that display content
|
||||
|
||||
3. composables/ migration
|
||||
Depends on: data/
|
||||
Blocks: pages that use useProjects(), useSeoMeta()
|
||||
|
||||
4. layouts/default.vue + TheHeader + TheFooter
|
||||
Depends on: @nuxtjs/i18n working, @nuxtjs/color-mode working
|
||||
Blocks: all page development (every page needs a shell)
|
||||
|
||||
5. pages/ migration (one page at a time, start with index.vue)
|
||||
Depends on: composables, layouts, Nuxt UI v3 components
|
||||
Blocks: nothing else — pages are leaf nodes
|
||||
|
||||
6. plugins/ (EmailJS, nuxt-gtag)
|
||||
Depends on: contact page, nuxt.config
|
||||
Blocks: contact form functionality, GA tracking
|
||||
|
||||
7. Dockerfile + deployment
|
||||
Depends on: all pages complete
|
||||
Blocks: production ship
|
||||
```
|
||||
|
||||
**Critical dependency:** `nuxt.config.ts` with `@nuxtjs/i18n`, `@nuxtjs/color-mode`, `@nuxt/ui`, and `@nuxtjs/sitemap` must be functional before any page/component work begins. All auto-imports, CSS variables, and the `useI18n()` composable availability depend on this configuration.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### Anti-Pattern 1: localStorage in SSR Context
|
||||
**What goes wrong:** `localStorage.setItem('locale', ...)` throws ReferenceError on server, causes hydration mismatch.
|
||||
**Prevention:** Use only `useCookie()` (Nuxt built-in) for any client-persisted state (locale, color mode). Both `@nuxtjs/i18n` and `@nuxtjs/color-mode` handle this when configured with `cookieName`.
|
||||
|
||||
### Anti-Pattern 2: `document.*` or `window.*` at module scope
|
||||
**What goes wrong:** Runs during SSR, crashes server render.
|
||||
**Prevention:** Wrap in `onMounted()` or use `import.meta.client` guard. The existing router `beforeEach` that calls `document.title` must move to `useSeoMeta()` calls inside each page.
|
||||
|
||||
### Anti-Pattern 3: Flat root structure (Nuxt 3 pattern in Nuxt 4)
|
||||
**What goes wrong:** Nuxt 4 expects `app/` as source directory. Files at project root are not auto-imported.
|
||||
**Prevention:** All Vue files, composables, components go under `app/`. Configure `srcDir: 'app'` in `nuxt.config.ts` (or rely on Nuxt 4 default).
|
||||
|
||||
### Anti-Pattern 4: useAsyncData for static data
|
||||
**What goes wrong:** `useAsyncData` with a static import adds unnecessary async overhead and serialization. Static data does not need SSR serialization.
|
||||
**Prevention:** Import static TS data directly in composables. Reserve `useAsyncData` for genuine async operations (external fetch, server routes).
|
||||
|
||||
### Anti-Pattern 5: Per-page SEO via router.beforeEach
|
||||
**What goes wrong:** `document.title` manipulation in router guards is SPA-only, invisible to crawlers.
|
||||
**Prevention:** Each page calls `useSeoMeta({ title, description, ogTitle, ogDescription, ogImage })` at setup scope — Nuxt handles server-side `<head>` injection.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- Nuxt 4 source directory convention: official Nuxt 4 migration guide (app/ directory)
|
||||
- Existing codebase analysis: `src/composables/`, `src/router/index.ts`, `src/locales/`
|
||||
- PROJECT.md constraints: cookie-only persistence, EmailJS, static TS data, Docker SSR deployment
|
||||
- Confidence: HIGH for Nuxt 4 file conventions; HIGH for SSR vs SSG decision given i18n cookie requirement; MEDIUM for @nuxtjs/i18n v9 prefix_except_default (verify exact config key names against current docs before implementing)
|
||||
Reference in New Issue
Block a user