Lord of the Rings Database - Next.js 15 Guide

You are an expert developer working on a comprehensive Lord of the Rings database website built with Next.js 15.

Project Context

This Next.js 15 project creates a LOTR database website that fetches data from The One API (https://the-one-api.dev). The application displays information about books, movies, characters, and quotes from the Lord of the Rings universe.

Technology Stack

Development Commands

When working with this project, use these commands:

File Structure

TypeScript Configuration

The One API Integration

API Configuration

Available Endpoints

1. `/book` - Books data (no auth, static generation)

2. `/movie` - Movies data (ISR with 1-hour revalidation)

3. `/character` - Characters data (server-side prefetch)

4. `/quote` - Quotes data (background sync)

5. `/chapter` - Chapters data (authenticated)

Caching Strategy

Apply these caching patterns when working with data:

Styling Architecture

The project uses Tailwind CSS v4 with the following patterns:

Code Patterns to Follow

1. Data Fetching

Use TanStack Query v5 for all API calls with appropriate caching strategies. Implement server-side prefetching where beneficial for performance.

2. Type Safety

Maintain strict TypeScript typing throughout. Define all API response types in `src/lib/types.ts`.

3. URL State Management

Use nuqs for managing URL state parameters (filtering, pagination, search).

4. Component Structure

Follow Next.js 15 App Router conventions with server components by default. Use client components only when necessary.

5. Performance Optimization

Environment Variables

Ensure `.env.local` contains:

```

THE_ONE_API_TOKEN=your_api_token_here

```

Important Constraints

1. **Rate Limiting**: Respect the 100 requests per 10 minutes limit from The One API

2. **Authentication**: All endpoints except `/book` require Bearer token authentication

3. **Font System**: Use only Geist Sans and Geist Mono fonts configured in root layout

4. **ESLint**: Follow Next.js core web vitals and TypeScript best practices

5. **Build Tool**: Always use Turbopack (configured in all npm scripts)

When Making Changes

1. **Read files first**: Always read existing code before suggesting modifications

2. **Maintain patterns**: Follow established patterns for API calls, caching, and styling

3. **Type safety**: Ensure all new code maintains strict TypeScript compliance

4. **Update progress**: Track progress in `todo.md` when appropriate

5. **Test locally**: Use `npm run dev` to verify changes before building

6. **Dark mode**: Ensure new styles support both light and dark themes

Examples

Adding a New API Endpoint

1. Add TypeScript types to `src/lib/types.ts`

2. Create API function in `src/lib/api.ts` with proper authentication

3. Implement TanStack Query hook with appropriate caching strategy

4. Create page component in `src/app/` following App Router conventions

5. Apply proper error handling and loading states

Styling New Components

1. Use Tailwind CSS utility classes

2. Support CSS custom properties for theming

3. Test in both light and dark modes

4. Follow existing spacing and typography patterns