Photo Portfolio with Next.js App Router

Build feature-rich photo portfolio applications with Next.js 15+ App Router, TypeScript, and Tailwind CSS. Supports modal navigation, theme switching, and multiple storage backends.

Project Architecture

Tech Stack

Directory Structure

```

src/

├── app/ # Next.js App Router

│ ├── @modal/ # Parallel route for modal display

│ ├── photo/[name]/ # Individual photo pages

│ └── (.)photo/[name]/ # Intercepting route for modals

├── features/ # Feature-based modules

│ ├── photo-wall/ # Gallery (thumbnails, full images, modal)

│ └── theme-switcher/ # Dark/light theme toggle

├── data/ # Pluggable storage adapters

│ ├── blob-storage/ # Azure Blob Storage

│ ├── file-system/ # Local file system

│ ├── google-photos/ # Google Photos API

│ └── dummy/ # Mock data for testing

├── content/ # Content configuration & metadata

└── public/photos/ # Static photo assets

```

Key Configuration Files

Code Conventions

TypeScript

1. Use strict mode (enabled by default)

2. Prefer type inference over explicit types

3. Use `interface` for objects, `type` for unions/intersections

4. Strongly type all components and functions

5. Reference the `Photo` type from `src/features/photo-wall/types/photo.ts`

React/Next.js Patterns

1. **Use Server Components by default** — Only add `'use client'` when needed (hooks, interactivity, context)

2. **Function components only** — Avoid class components

3. **Image optimization** — Always use `next/image` for photos

4. **Routing** — Leverage intercepting routes for modal navigation

5. **Data fetching** — Use Server Components for data loading when possible

Styling

1. **Tailwind utility classes** — Avoid custom CSS unless necessary

2. **Mobile-first responsive design** — Use `sm:`, `md:`, `lg:` breakpoints

3. **Dark mode support** — Use `dark:` variants, maintain theme compatibility

4. **Semantic HTML** — Use proper heading hierarchy and ARIA attributes

Testing

1. Place test files alongside implementation (`.test.ts`, `.test.tsx`)

2. Use Vitest for unit tests

3. Test utilities, components, and data layers

4. Run with `npm run test`

Data Layer Pattern

The app uses a **pluggable data provider pattern** for flexible photo sources:

1. **Define data source** in `app.config.ts`

2. **Implement provider interface** with consistent `Photo` type output

3. **Fetch and transform** photos from local files, cloud storage, or APIs

4. **Supported backends**: Local file system, Azure Blob Storage, Google Photos, dummy data

Feature Patterns

Photo Wall

Theme Switching

Performance Best Practices

1. **Image optimization** — Use Next.js `<Image>` component with proper `sizes` attribute

2. **Lazy loading** — Implement for thumbnail grid

3. **Preload adjacent images** — In modal view for smooth navigation

4. **Throttle/debounce** — Use for scroll and resize event handlers

5. **Code splitting** — Leverage dynamic imports for large components

Accessibility Requirements

1. **Alt text** — All images must have descriptive alt attributes

2. **Keyboard navigation** — Support arrow keys, Escape, Tab throughout

3. **Focus management** — Trap focus in modals, restore on close

4. **ARIA labels** — Use on interactive elements (theme switcher, modal controls)

5. **Semantic HTML** — Use `<nav>`, `<article>`, `<figure>` appropriately

Development Workflow

Setup

```bash

npm install

npm run dev # Start development server

npm run test # Run tests

npm run build # Production build

```

Docker Deployment

Use the provided `Dockerfile` for containerized deployment.

Common Implementation Tasks

Adding Photos

1. Place image in `public/photos/`

2. Add entry to `src/content/content.json`:

```json

{

"name": "photo-name",

"title": "Photo Title",

"description": "Optional description",

"date": "2024-01-15"

}

```

3. Verify it appears in the gallery

Creating Components

1. Create component in appropriate feature folder (e.g., `src/features/photo-wall/components/`)

2. Add TypeScript types/interfaces

3. Write corresponding `.test.tsx` file

4. Export from feature `index.ts` if needed externally

5. Follow naming convention: `PascalCase` for components, `camelCase` for utilities

Adding Storage Backends

1. Create provider folder under `src/data/`

2. Implement data provider interface

3. Transform data to `Photo` type

4. Add tests in `data.test.ts`

5. Update `app.config.ts` to enable new source

Styling Components

1. Use existing Tailwind classes when possible

2. Extend `tailwind.config.ts` for custom values (colors, spacing, etc.)

3. Test dark mode with `dark:` variants

4. Verify responsive behavior at all breakpoints (`sm`, `md`, `lg`, `xl`)

Navigation Architecture

Modal Routing

Keyboard Shortcuts

Debugging Tips

1. **Browser console** — Check for client-side errors

2. **Next.js build output** — Review for SSR/hydration issues

3. **React DevTools** — Inspect component tree and props

4. **Image paths** — Verify relative paths and optimization settings

5. **Network tab** — Check image loading and API calls

Best Practices Summary

Important Notes