feat: resume download, router v7/v8 migrations, spec restructure

- Add resume download button in Hero CTA and Contact section
- Migrate react-router v6→v7 and v7→v8
- Restructure specs: UI specs to specs/ui/, v2 specs to specs/v2/
- Add profile-photo assets (jpg + webp)
- Update AGENTS.md, spec-v2.md index
This commit is contained in:
dong.nguyen committed 2026-10-06 14:14:01 +07:00
1 parent 02bad6036d
commit d827bf9b23
37 files changed
+770 -443

No files matched your search

+3 -2
View File
@@ -96,8 +96,9 @@ All specification documents are in `docs/design/`:
|------|---------|
| `spec.md` | Main PRD — product vision, positioning, narrative, IA, acceptance criteria |
| `spec-v1.md` | v1 completion record — features implemented, known limitations, files summary |
| `spec-v2.md` | v2 features — Resume, Blog, SEO, Analytics, Testing, CI/CD |
| `spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) |
| `spec-v2.md` | v2 index — overview, implementation order, feature list |
| `specs/ui/spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) |
| `specs/v2/spec-v2-*.md` | v2 feature specs (resume, seo, blog, analytics, testing, cicd) |
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
+19 -410
View File
@@ -8,418 +8,27 @@
---
## Prerequisites (Completed)
| File | Feature | Status |
|------|---------|--------|
| `specs/v2/spec-v2-router.md` | React Router v6 → v7 | ✅ Done |
| `specs/v2/spec-v2-router-v8.md` | React Router v7 → v8 | ✅ Done |
## Overview
Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào:
1. **Resume download** (P1)
2. **Blog system** — MDX-based articles (P1)
3. **SEO** — metadata, Open Graph, sitemap (P1)
4. **Analytics** — privacy-friendly page view tracking (P2)
5. **Testing** — Vitest + Testing Library (P5)
6. **CI/CD pipeline** (P5)
---
## 1. Resume Download
### Requirement
- Nút "Download Resume" trong nav hoặc Contact page
- Link đến file PDF (placeholder ban đầu)
- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon"
- PDF sẽ upload vào `public/resume.pdf`
### Implementation
```tsx
// Navigation.tsx
{resumeAvailable && (
<Link to="/resume" className="nav-link">Resume</Link>
)}
// OR ContactPage.tsx
<a href="/resume.pdf" download className="btn-primary">Download Resume</a>
```
### Data
- `public/resume.pdf` — PDF file (user tự upload)
- Không cần data module
### Acceptance
- [ ] Nút Resume hiển thị trong nav
- [ ] Click → download PDF
- [ ] Khi chưa có PDF → nút ẩn hoặc disabled
- [ ] Responsive trên mobile
---
## 2. Blog System
### Requirement
Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
### Architecture
```
src/
content/
blog/
post-1.mdx
post-2.mdx
components/
blog/
BlogListPage.tsx
BlogPostPage.tsx
ArticleCard.tsx
CodeBlock.tsx
```
### Features
#### 2.1. Frontmatter
Mỗi article có frontmatter:
```yaml
---
title: "Building High-Performance Event Simulation with Go"
date: "2024-06-15"
tags: ["engineering", "golang", "simulation"]
summary: "Discrete event simulation for logistics facilities"
---
```
#### 2.2. Blog List Page (`/blog`)
- Hiển thị danh sách articles
- Sort theo date (newest first)
- Filter theo tags (pill buttons)
- Mỗi article card: title, date, tags, summary
#### 2.3. Article Page (`/blog/:slug`)
- Render MDX content
- Code blocks với syntax highlighting
- TOC (table of contents) sidebar (desktop)
- Reading time estimate
- Breadcrumb navigation
#### 2.4. Code Highlighting
- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
- Không dùng library nặng như `react-syntax-highlighter`
- Theme: dark/light compatible với CSS variables
#### 2.5. MDX Processing
- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
- Build-time compilation (không runtime)
- Frontmatter extracted tại build time
### Vite Config Changes
```ts
// vite.config.ts
import mdx from '@mdx-js/rollup'
export default defineConfig({
plugins: [
react(),
mdx({
providerImportSource: '@mdx-js/react',
}),
],
})
```
### Acceptance
- [ ] `/blog` hiển thị danh sách articles
- [ ] Article card có title, date, tags, summary
- [ ] Click article → navigate đến `/blog/:slug`
- [ ] MDX content render đúng
- [ ] Code blocks có syntax highlighting
- [ ] Tags filter hoạt động
- [ ] TOC sidebar (desktop only)
- [ ] Reading time hiển thị
- [ ] Responsive
- [ ] Không crash khi missing article
---
## 3. SEO
### Requirement
Mỗi page có metadata riêng cho SEO và social sharing.
### Implementation
#### 3.1. Dynamic Metadata
Dùng `react-helmet-async` (hoặc `@remix-run/react` helmet nếu cần SSR sau này).
```tsx
import { Helmet } from 'react-helmet-async'
// HomePage.tsx
<Helmet>
<title>{profile.name} — Senior Software Engineer</title>
<meta name="description" content={profile.bio} />
<link rel="canonical" href={siteUrl} />
</Helmet>
```
#### 3.2. Open Graph
Mỗi page có OG tags:
```html
<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:image" content="/og-image.png" />
<meta property="og:url" content="..." />
<meta property="og:type" content="website" />
```
#### 3.3. Sitemap
- Generate `sitemap.xml` tại build time
- Dùng `vite-plugin-sitemap` hoặc tự viết script
- Include tất cả public pages
#### 3.4. Robots.txt
- `public/robots.txt`
- Allow all (trừ `/admin` nếu có sau này)
#### 3.5. Structured Data (JSON-LD)
- `Person` schema cho homepage
- `Article` schema cho blog posts
- `BreadcrumbList` cho nested pages
### Acceptance
- [ ] Mỗi page có `<title>` và `<meta description>` riêng
- [ ] OG tags đúng trên mỗi page
- [ ] `sitemap.xml` generated tại build
- [ ] `robots.txt` có trong `public/`
- [ ] JSON-LD structured data
- [ ] Canonical URL đúng
---
## 4. Analytics
### Requirement
Privacy-friendly analytics — không dùng Google Analytics.
### Options
**Option A: Plausible Analytics** (recommended)
- Lightweight, privacy-first
- No cookie banner needed
- Simple script integration
**Option B: Umami**
- Self-hosted option
- Open source
- Similar to Plausible
**Option C: Custom minimal tracking**
- Track page views only
- Store in localStorage
- Batch send to endpoint (optional)
### Implementation (Plausible)
```tsx
// main.tsx
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.outbound-links.js"
/>
```
Hoặc dùng `react-use-plausible`:
```tsx
import { usePlausible } from 'react-use-plausible'
const plausible = usePlausible()
// Auto pageview tracking
```
### Acceptance
- [ ] Page view tracking hoạt động
- [ ] Không cookie banner
- [ ] Không ảnh hưởng performance
- [ ] Configurable via env var (ENABLE_ANALYTICS)
---
## 5. Testing
### Requirement
Unit tests cho components và hooks. E2E tests cho critical paths.
### Stack
- **Vitest** — unit/integration tests
- **@testing-library/react** — component tests
- **@testing-library/jest-dom** — assertions
- **Playwright** — E2E tests
### Test Structure
```
src/
__tests__/
hooks/
useTheme.test.tsx
components/
Navigation.test.tsx
Footer.test.tsx
Badge.test.tsx
pages/
HomePage.test.tsx
e2e/
navigation.spec.ts
theme.spec.ts
responsive.spec.ts
```
### Critical Tests
#### useTheme
```tsx
test('cycles through themes correctly', () => {
const { result } = renderHook(() => useTheme())
act(() => { result.current.cycleTheme() })
expect(result.current.theme).toBe('light') // or 'dark'
})
test('persists theme to localStorage', () => {
renderHook(() => useTheme())
expect(localStorage.getItem('portfolio-theme')).toBe('dark')
})
```
#### Navigation
```tsx
test('renders all nav items', () => {
render(<Navigation />)
navItems.forEach(item => {
expect(screen.getByText(item.label)).toBeInTheDocument()
})
})
test('NavLink highlights active route', () => {
render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>)
expect(screen.getByText('About')).toHaveClass('active')
})
```
#### HomePage
```tsx
test('renders hero section', () => {
render(<HomePage />)
expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
})
```
### Acceptance
- [ ] useTheme tests pass
- [ ] Navigation tests pass
- [ ] HomePage tests pass
- [ ] E2E: navigation works
- [ ] E2E: theme toggle works
- [ ] E2E: responsive layout correct
- [ ] Test coverage > 70%
---
## 6. CI/CD Pipeline
### Requirement
GitHub Actions pipeline:
1. **Lint** — oxlint
2. **Type check** — tsc -b
3. **Test** — vitest
4. **Build** — vite build
5. **Deploy** — to Vercel (on main branch push)
### GitHub Actions
```yaml
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [dev, main]
pull_request:
branches: [dev]
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm build
- run: pnpm test
```
### Vercel Integration
- Connect GitHub repo
- Auto deploy on `dev` → preview
- Auto deploy on `main` → production
- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
### Acceptance
- [ ] CI pass trên push vào dev
- [ ] Lint pass
- [ ] Build pass
- [ ] Tests pass
- [ ] Preview deploy trên Vercel
- [ ] Production deploy khi merge vào main
---
## Implementation Order
Ưu tiên thực hiện:
1. **Resume download** (5 phút, trivial)
2. **SEO** (metadata, OG, sitemap) — cần làm trước khi deploy
3. **Blog system** (MDX + articles) — P1, substantial work
4. **Analytics** (Plausible) — quick win
5. **Testing** (Vitest + E2E) — P5, important but can iterate
6. **CI/CD** (GitHub Actions) — P5, automate after features done
v2 bao gồm 6 tính năng, mỗi tính năng có spec riêng trong `specs/`:
| File | Feature | Priority | Est. | Status |
|------|---------|----------|------|--------|
| `specs/v2/spec-v2-resume.md` | Resume download | P1 | ~15 min | ✅ Done |
| `specs/v2/spec-v2-seo.md` | SEO (metadata, OG, sitemap) | P1 | ~1 hour | |
| `specs/v2/spec-v2-blog.md` | Blog (MDX, articles, syntax highlight) | P1 | ~4 hours | |
| `specs/v2/spec-v2-analytics.md` | Analytics (Plausible) | P2 | ~30 min | |
| `specs/v2/spec-v2-testing.md` | Testing (Vitest + E2E) | P5 | ~3 hours | |
| `specs/v2/spec-v2-cicd.md` | CI/CD (GitHub Actions) | P5 | ~1 hour | |
**Implementation order:** ~~Resume~~ → SEO → Blog → Analytics → Testing → CI/CD
---
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+65
View File
@@ -0,0 +1,65 @@
# Specification — v2 Analytics
> **Document:** `spec-v2-analytics.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P2
> **Estimate:** ~30 minutes
---
## Requirement
Privacy-friendly analytics — không dùng Google Analytics.
---
## Options
**Option A: Plausible Analytics** (recommended)
- Lightweight, privacy-first
- No cookie banner needed
- Simple script integration
**Option B: Umami**
- Self-hosted option
- Open source
- Similar to Plausible
**Option C: Custom minimal tracking**
- Track page views only
- Store in localStorage
- Batch send to endpoint (optional)
---
## Implementation (Plausible)
```tsx
// main.tsx — add script tag
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.outbound-links.js"
/>
```
Hoặc dùng `react-use-plausible`:
```tsx
import { usePlausible } from 'react-use-plausible'
const plausible = usePlausible()
// Auto pageview tracking
```
Configurable via env var: `ENABLE_ANALYTICS`
---
## Acceptance
- [ ] Page view tracking hoạt động
- [ ] Không cookie banner
- [ ] Không ảnh hưởng performance
- [ ] Configurable via env var (ENABLE_ANALYTICS)
+105
View File
@@ -0,0 +1,105 @@
# Specification — v2 Blog System
> **Document:** `spec-v2-blog.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~4 hours
---
## Requirement
Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
---
## Architecture
```
src/
content/
blog/
post-1.mdx
post-2.mdx
components/
blog/
BlogListPage.tsx
BlogPostPage.tsx
ArticleCard.tsx
CodeBlock.tsx
```
---
## Features
### Frontmatter
Mỗi article có frontmatter:
```yaml
---
title: "Building High-Performance Event Simulation with Go"
date: "2024-06-15"
tags: ["engineering", "golang", "simulation"]
summary: "Discrete event simulation for logistics facilities"
---
```
### Blog List Page (`/blog`)
- Hiển thị danh sách articles
- Sort theo date (newest first)
- Filter theo tags (pill buttons)
- Mỗi article card: title, date, tags, summary
### Article Page (`/blog/:slug`)
- Render MDX content
- Code blocks với syntax highlighting
- TOC (table of contents) sidebar (desktop)
- Reading time estimate
- Breadcrumb navigation
### Code Highlighting
- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
- Không dùng library nặng như `react-syntax-highlighter`
- Theme: dark/light compatible với CSS variables
### MDX Processing
- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
- Build-time compilation (không runtime)
- Frontmatter extracted tại build time
### Vite Config Changes
```ts
import mdx from '@mdx-js/rollup'
export default defineConfig({
plugins: [
react(),
mdx({
providerImportSource: '@mdx-js/react',
}),
],
})
```
---
## Acceptance
- [ ] `/blog` hiển thị danh sách articles
- [ ] Article card có title, date, tags, summary
- [ ] Click article → navigate đến `/blog/:slug`
- [ ] MDX content render đúng
- [ ] Code blocks có syntax highlighting
- [ ] Tags filter hoạt động
- [ ] TOC sidebar (desktop only)
- [ ] Reading time hiển thị
- [ ] Responsive
- [ ] Không crash khi missing article
+61
View File
@@ -0,0 +1,61 @@
# Specification — v2 CI/CD Pipeline
> **Document:** `spec-v2-cicd.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P5
> **Estimate:** ~1 hour
---
## Requirement
GitHub Actions pipeline cho automated build, lint, test. Vercel cho deployment.
---
## GitHub Actions
```yaml
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [dev, main]
pull_request:
branches: [dev]
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm build
- run: pnpm test
```
## Vercel Integration
- Connect GitHub repo
- Auto deploy on `dev` → preview
- Auto deploy on `main` → production
- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
---
## Acceptance
- [ ] CI pass trên push vào dev
- [ ] Lint pass
- [ ] Build pass
- [ ] Tests pass
- [ ] Preview deploy trên Vercel
- [ ] Production deploy khi merge vào main
+104
View File
@@ -0,0 +1,104 @@
# Specification — v2 Resume Download
> **Document:** `spec-v2-resume.md`
> **Version:** 0.3.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~15 minutes
---
## Requirement
- Nút **"Download Resume"** hiển thị ở **2 vị trí**:
1. **Hero section** — CTA row (bên cạnh "View Projects" / "Contact Me")
2. **Contact section** — trong `contact-links` grid
- Link trực tiếp đến file PDF (`/resume.pdf`) với attribute `download`
- Khi chưa có PDF → ẩn hoàn toàn ở cả 2 vị trí
- PDF upload vào `public/resume.pdf`
- (Optional) Nav link `/resume` để xem resume dạng HTML (Phase 2+)
---
## Implementation
### Hero Section (primary CTA)
```tsx
// Hero.tsx
import { resumeAvailable } from '@/data/resume'
export function Hero() {
return (
<section className="hero container-wide" aria-labelledby="hero-heading">
<div className="hero-content">
{/* ... heading, title, tagline ... */}
<div className="hero-cta">
<Button href="/projects" variant="primary">
View Projects
</Button>
{resumeAvailable && (
<Button href="/resume.pdf" variant="secondary" download>
Download Resume
</Button>
)}
<Button href="/contact" variant="secondary">
Contact Me
</Button>
</div>
<SocialLinks links={socialLinks} />
</div>
{/* ... hero-visual ... */}
</section>
)
}
```
### Contact Section (secondary)
```tsx
// Contact.tsx
import { resumeAvailable } from '@/data/resume'
export function Contact() {
return (
<section className="section container-content" aria-labelledby="contact-heading">
<SectionHeading title="Contact" />
<div className="contact-links">
{/* ... existing links (Email, GitHub, LinkedIn) ... */}
{resumeAvailable && (
<a href="/resume.pdf" download className="contact-link btn-primary">
<svg>...</svg>
<div>
<div>Download Resume</div>
<div style={{ fontSize: '14px', color: 'var(--text-muted)' }}>PDF</div>
</div>
</a>
)}
</div>
</section>
)
}
```
### Data Detection
```ts
// src/data/resume.ts
export const resumeAvailable = true // set false khi chưa có PDF
```
### Nav (optional — Phase 2)
Nút Resume trong nav chỉ hiện khi có `/resume` route (HTML resume page).
---
## Acceptance
- [x] Nút "Download Resume" hiển thị trong Hero CTA row
- [x] Nút "Download Resume" hiển thị trong Contact section
- [x] Click → download PDF từ `/resume.pdf`
- [x] Khi chưa có PDF → ẩn hoàn toàn ở cả 2 vị trí
- [x] Responsive trên mobile
- [x] Nav không có nút Resume (Phase 2)
+94
View File
@@ -0,0 +1,94 @@
# Specification — v2 React Router v7 → v8 Migration
> **Document:** `spec-v2-router-v8.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P0 (prerequisite for v2)
> **Estimate:** ~15 minutes
---
## Background
React Router v8 consolidates DOM APIs into `react-router/dom` and removes the `react-router-dom` re-export package. This app uses only the declarative mode (`<BrowserRouter>` + `<Routes>` + `<Route>`) — no data router, no loaders, no actions, no meta functions, no splat routes.
**Current state:**
- `react-router` pinned at `7.18.4`
- 4 files import from `react-router`
- No `react-router-dom` (already removed in v7 migration)
- No `meta` functions, no `useMatches().data`, no data router APIs
- React `^19.2.8` (≥ 19.2.7 ✅)
- Vite `^8.3.0` (≥ 7 ✅)
---
## Analysis
### Future flags
All 5 future flags are framework/data mode only. **Not applicable** to this app:
| Flag | Applicable? | Notes |
|------|-------------|-------|
| `v8_middleware` | No | No data router / framework mode |
| `v8_splitRouteModules` | No | No `<RouterProvider>` / data router |
| `v8_viteEnvironmentApi` | No | No SSR / custom server config |
| `v8_passThroughRequests` | No | No loaders/actions |
| `v8_trailingSlashAwareDataRequests` | No | No `.data` request handling |
### Breaking changes
| Change | Applicable? | Notes |
|--------|-------------|-------|
| `meta`/`matches` `.data` → `loaderData` | No | No meta functions |
| `react-router-dom` removal | No | Already removed in v7 migration |
| Cloudflare plugin | No | Not using Cloudflare |
| `@react-router/architect` | No | Not using adapters |
### Minimum versions
| Requirement | Current | Required | Status |
|-------------|---------|----------|--------|
| `react` | `^19.2.8` | `≥19.2.7` | ✅ |
| `react-dom` | `^19.2.8` | `≥19.2.7` | ✅ |
| `vite` | `^8.3.0` | `≥7` | ✅ |
---
## Implementation Steps
### Step 1: Update package.json
```diff
- "react-router": "7.18.4"
+ "react-router": "8.4.0"
```
### Step 2: Install and verify
```sh
pnpm install
pnpm build
pnpm lint
```
---
## Acceptance
- [x] `package.json` has `react-router@8.4.0`
- [x] `pnpm build` succeeds without errors
- [x] Dev server runs without console warnings
- [x] All routes work correctly (/ → /about → /projects → /projects/:id → /engineering → /contact)
- [x] Navigation highlighting works (NavLink active state)
- [x] Mobile menu still works
- [x] Project detail page works (useParams + Link)
---
## Notes
- v8 upgrade is non-breaking for this app (pure declarative `<BrowserRouter>` pattern)
- No code changes needed — only package version bump
- `react-router-dom` already removed in v7 migration
- All future flags are framework/data mode only, not applicable to this app
+98
View File
@@ -0,0 +1,98 @@
# Specification — v2 React Router v6 → v7 Migration
> **Document:** `spec-v2-router.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P0 (prerequisite for v2)
> **Estimate:** ~30 minutes
---
## Background
React Router v7 consolidates `react-router-dom` into `react-router`. The upgrade is non-breaking if future flags are enabled. This app uses the simple `<BrowserRouter>` + `<Routes>` pattern (no data router, no forms, no splat routes).
**Current state:**
- `react-router-dom` pinned at `6.30.6` (exact, no `^`)
- 4 files import from `react-router-dom`
- No splat routes, no forms, no data router APIs
---
## Analysis
### Applicable flags
| Flag | Applicable? | Notes |
|------|-------------|-------|
| `v7_relativeSplatPath` | No | No splat routes (`*`) in app |
| `v7_startTransition` | **Yes** | Must enable on `<BrowserRouter>` |
| `v7_fetcherPersist` | No | No `<RouterProvider>` / data router |
| `v7_normalizeFormMethod` | No | No forms in app |
| `v7_partialHydration` | No | No `<RouterProvider>` / data router |
| `v7_skipActionErrorRevalidation` | No | No data router |
### Files affected
| File | Current import | Change needed |
|------|---------------|---------------|
| `src/App.tsx` | `react-router-dom` | → `react-router` + enable flag |
| `src/components/layout/Navigation.tsx` | `react-router-dom` | → `react-router` |
| `src/components/layout/Footer.tsx` | `react-router-dom` | → `react-router` |
| `src/pages/ProjectDetailPage.tsx` | `react-router-dom` | → `react-router` |
---
## Implementation Steps
### Step 1: Verify no future flags needed
In v7, `v7_startTransition` and other future flags are enabled by default. No `future` prop needed on `<BrowserRouter>`.
### Step 2: Update package.json
```diff
- "react-router-dom": "6.30.6"
+ "react-router": "7.18.4"
```
Also remove `@types/react-router-dom` if present (v7 types are bundled).
### Step 3: Update imports
All files: replace `from 'react-router-dom'` → `from 'react-router'`
```
src/App.tsx
src/components/layout/Navigation.tsx
src/components/layout/Footer.tsx
src/pages/ProjectDetailPage.tsx
```
### Step 4: Install and verify
```bash
pnpm install
pnpm build
```
---
## Acceptance
- [x] `package.json` has `react-router` (not `react-router-dom`)
- [x] All 4 files import from `react-router`
- [x] `pnpm build` succeeds without errors
- [x] Dev server runs without console warnings
- [x] All routes work correctly (/ → /about → /projects → /projects/:id → /engineering → /contact)
- [x] Navigation highlighting works (NavLink active state)
- [x] Mobile menu still works
---
## Notes
- v7 upgrade is non-breaking for this app (simple `<BrowserRouter>` pattern)
- No code logic changes needed — only imports + package name
- v7 enables all future flags by default; no `future` prop needed
+72
View File
@@ -0,0 +1,72 @@
# Specification — v2 SEO
> **Document:** `spec-v2-seo.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~1 hour
---
## Requirement
Mỗi page có metadata riêng cho SEO và social sharing.
---
## Implementation
### Dynamic Metadata
Dùng `react-helmet-async`.
```tsx
import { Helmet } from 'react-helmet-async'
// HomePage.tsx
<Helmet>
<title>{profile.name} — Senior Software Engineer</title>
<meta name="description" content={profile.bio} />
<link rel="canonical" href={siteUrl} />
</Helmet>
```
### Open Graph
Mỗi page có OG tags:
```html
<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:image" content="/og-image.png" />
<meta property="og:url" content="..." />
<meta property="og:type" content="website" />
```
### Sitemap
- Generate `sitemap.xml` tại build time
- Dùng `vite-plugin-sitemap` hoặc tự viết script
- Include tất cả public pages
### Robots.txt
- `public/robots.txt`
- Allow all
### Structured Data (JSON-LD)
- `Person` schema cho homepage
- `Article` schema cho blog posts (sau này)
- `BreadcrumbList` cho nested pages
---
## Acceptance
- [ ] Mỗi page có `<title>` và `<meta description>` riêng
- [ ] OG tags đúng trên mỗi page
- [ ] `sitemap.xml` generated tại build
- [ ] `robots.txt` có trong `public/`
- [ ] JSON-LD structured data
- [ ] Canonical URL đúng
+99
View File
@@ -0,0 +1,99 @@
# Specification — v2 Testing
> **Document:** `spec-v2-testing.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P5
> **Estimate:** ~3 hours
---
## Requirement
Unit tests cho components và hooks. E2E tests cho critical paths.
---
## Stack
- **Vitest** — unit/integration tests
- **@testing-library/react** — component tests
- **@testing-library/jest-dom** — assertions
- **Playwright** — E2E tests
---
## Test Structure
```
src/
__tests__/
hooks/
useTheme.test.tsx
components/
Navigation.test.tsx
Footer.test.tsx
Badge.test.tsx
pages/
HomePage.test.tsx
e2e/
navigation.spec.ts
theme.spec.ts
responsive.spec.ts
```
---
## Critical Tests
### useTheme
```tsx
test('cycles through themes correctly', () => {
const { result } = renderHook(() => useTheme())
act(() => { result.current.cycleTheme() })
expect(result.current.theme).toBe('light')
})
test('persists theme to localStorage', () => {
renderHook(() => useTheme())
expect(localStorage.getItem('portfolio-theme')).toBe('dark')
})
```
### Navigation
```tsx
test('renders all nav items', () => {
render(<Navigation />)
navItems.forEach(item => {
expect(screen.getByText(item.label)).toBeInTheDocument()
})
})
test('NavLink highlights active route', () => {
render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>)
expect(screen.getByText('About')).toHaveClass('active')
})
```
### HomePage
```tsx
test('renders hero section', () => {
render(<HomePage />)
expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
})
```
---
## Acceptance
- [ ] useTheme tests pass
- [ ] Navigation tests pass
- [ ] HomePage tests pass
- [ ] E2E: navigation works
- [ ] E2E: theme toggle works
- [ ] E2E: responsive layout correct
- [ ] Test coverage > 70%
+1 -1
View File
@@ -12,7 +12,7 @@
"dependencies": {
"react": "^19.2.8",
"react-dom": "^19.2.8",
"react-router-dom": "6.30.6"
"react-router": "8.4.0"
},
"devDependencies": {
"@types/node": "^24.13.3",
+23 -26
View File
@@ -14,9 +14,9 @@ importers:
react-dom:
specifier: ^19.2.8
version: 19.3.0(react@19.3.0)
react-router-dom:
specifier: 6.30.6
version: 6.30.6(react-dom@19.3.0(react@19.3.0))(react@19.3.0)
react-router:
specifier: 8.4.0
version: 8.4.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0)
devDependencies:
'@types/node':
specifier: ^24.13.3
@@ -167,9 +167,8 @@ packages:
cpu: [x64]
os: [win32]
'@remix-run/router@1.23.4':
resolution: {integrity: sha512-q7j5geK7xs3UJSdm9/iytUNclBnLmYx1EnSeCFXHPeutdqgIMeFeHtUZgS3EhlKxdBEAu8OwtJCwmLrEzpSs7Q==}
engines: {node: '>=14.0.0'}
'@remix-run/route-pattern@0.22.1':
resolution: {integrity: sha512-czdGJWh09Lapvcqt7Vb09KlrU2PhRJ8xQaI+AItTuD9aDJ5MAgxnS38lnys6Ll+6RJEqPiaUqTwIQhVLwFvv+w==}
'@rolldown/binding-android-arm-eabi@1.2.12':
resolution: {integrity: sha512-dB/a1214qKfHMXCpgqR4OZT+jS4kTyEXbQGJPqzobt5EwH5rX080pxE37alt3RzvR1bf1Yz/yGqRfrYAxuPw0A==}
@@ -297,6 +296,9 @@ packages:
oxc-transform-react:
optional: true
cookie-es@3.1.1:
resolution: {integrity: sha512-UaXxwISYJPTr9hwQxMFYZ7kNhSXboMXP+Z3TRX6f1/NyaGPfuNUZOWP1pUEb75B2HjfklIYLVRfWiFZJyC6Npg==}
csstype@3.2.3:
resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
@@ -426,18 +428,15 @@ packages:
peerDependencies:
react: ^19.3.0
react-router-dom@6.30.6:
resolution: {integrity: sha512-0RHKZz7wwffvkU+2MFVT2NnjK44ssLEV+m0CAJaS2Ksmorrwj7WxH00jO0SOCW26/tINUnJHToXblDs33I38YQ==}
engines: {node: '>=14.0.0'}
react-router@8.4.0:
resolution: {integrity: sha512-JtydAkBvU9UTEe5qNC+POhu+ZBNM7rlKY2IegwXc7Idj7xfRG16x5RZrw3mju+XlqBxfvb2ky9P3jUp9WyWC1g==}
engines: {node: '>=22.22.0'}
peerDependencies:
react: '>=16.8'
react-dom: '>=16.8'
react-router@6.30.6:
resolution: {integrity: sha512-5HfK7k5im7LTOB0EqCQmfvy4C13G92Ssj1VTmouTK3AJvyjKTnFuCV0vcMAD/JS+JC4DvDIBRrlAeJIFjh5VWg==}
engines: {node: '>=14.0.0'}
peerDependencies:
react: '>=16.8'
react: '>=19.2.7'
react-dom: '>=19.2.7'
peerDependenciesMeta:
react-dom:
optional: true
react@19.3.0:
resolution: {integrity: sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==}
@@ -571,7 +570,7 @@ snapshots:
'@oxlint/binding-win32-x64-msvc@1.86.0':
optional: true
'@remix-run/router@1.23.4': {}
'@remix-run/route-pattern@0.22.1': {}
'@rolldown/binding-android-arm-eabi@1.2.12':
optional: true
@@ -637,6 +636,8 @@ snapshots:
'@rolldown/pluginutils': 1.0.1
vite: 8.3.2(@types/node@24.19.1)
cookie-es@3.1.1: {}
csstype@3.2.3: {}
detect-libc@2.1.2: {}
@@ -736,17 +737,13 @@ snapshots:
react: 19.3.0
scheduler: 0.28.0
react-router-dom@6.30.6(react-dom@19.3.0(react@19.3.0))(react@19.3.0):
react-router@8.4.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0):
dependencies:
'@remix-run/router': 1.23.4
'@remix-run/route-pattern': 0.22.1
cookie-es: 3.1.1
react: 19.3.0
optionalDependencies:
react-dom: 19.3.0(react@19.3.0)
react-router: 6.30.6(react@19.3.0)
react-router@6.30.6(react@19.3.0):
dependencies:
'@remix-run/router': 1.23.4
react: 19.3.0
react@19.3.0: {}
Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 898 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

+1 -1
View File
@@ -1,5 +1,5 @@
import './App.css'
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import { BrowserRouter, Routes, Route } from 'react-router'
import { ThemeProvider } from '@/hooks/useTheme'
import { Layout } from '@/components/layout/Layout'
import {
+1 -1
View File
@@ -1,4 +1,4 @@
import { Link } from 'react-router-dom'
import { Link } from 'react-router'
import { profile } from '@/data/profile'
const footerLinks = [
+1 -1
View File
@@ -1,5 +1,5 @@
import { useState, useEffect } from 'react'
import { Link, NavLink, useLocation } from 'react-router-dom'
import { Link, NavLink, useLocation } from 'react-router'
import { useTheme } from '@/hooks/useTheme'
const navItems = [
+14
View File
@@ -1,3 +1,4 @@
import { resumeAvailable } from '@/data/resume'
import { SectionHeading } from '@/components/ui/SectionHeading'
import { profile } from '@/data/profile'
@@ -34,6 +35,19 @@ export function Contact() {
<div style={{ fontSize: '14px', color: 'var(--text-muted)' }}>Your Name</div>
</div>
</a>
{resumeAvailable && (
<a href="/resume.pdf" download className="contact-link">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" width="24" height="24">
<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
<polyline points="7 10 12 15 17 10" />
<line x1="12" y1="15" x2="12" y2="3" />
</svg>
<div>
<div style={{ fontWeight: 500, color: 'var(--text-primary)' }}>Download Resume</div>
<div style={{ fontSize: '14px', color: 'var(--text-muted)' }}>PDF</div>
</div>
</a>
)}
</div>
</section>
)
+6
View File
@@ -1,3 +1,4 @@
import { resumeAvailable } from '@/data/resume'
import { Button } from '@/components/ui/Button'
import { SocialLinks } from '@/components/ui/SocialLinks'
import { profile } from '@/data/profile'
@@ -49,6 +50,11 @@ export function Hero() {
<Button href="/projects" variant="primary">
View Projects
</Button>
{resumeAvailable && (
<Button href="/resume.pdf" variant="secondary" download>
Download Resume
</Button>
)}
<Button href="/contact" variant="secondary">
Contact Me
</Button>
+1
View File
@@ -8,6 +8,7 @@ interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
variant?: ButtonVariant
size?: ButtonSize
href?: string
download?: boolean
children: React.ReactNode
}
+1
View File
@@ -0,0 +1 @@
export const resumeAvailable = true
+1 -1
View File
@@ -1,4 +1,4 @@
import { useParams, Link } from 'react-router-dom'
import { useParams, Link } from 'react-router'
import { Badge } from '@/components/ui/Badge'
import { Tag } from '@/components/ui/Tag'
import { projects } from '@/data/projects'