Init commit from initial prompt

2025-08-17 12:21:15 +01:00
commit caee8e27f2
21 changed files with 3114 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,114 @@
+# Magikarp Collection
+
+A Next.js web app to browse every English Magikarp Pokémon card with images, set symbols, search, set filter, and a personal checklist stored in your browser.
+
+## Features
+- **Checklist**: Mark cards as collected (stored in `localStorage`).
+- **Card images**: Uses official images from `images.pokemontcg.io`.
+- **Set symbols**: Displays set symbol and series/name.
+- **Search & filter**: Search by name/number/rarity/set and filter by set.
+- **Responsive UI**: Tailwind CSS, mobile-friendly grid.
+
+## Tech Stack
+- **Next.js 15** (App Router)
+- **React 19**
+- **TypeScript**
+- **Tailwind CSS v4**
+- **Axios** for HTTP
+
+## Quick Start
+
+### 1) Prerequisites
+- Node.js 18+ and npm
+
+### 2) Install dependencies
+```bash
+npm install
+```
+
+### 3) Environment variables
+Get a free Pokémon TCG API key: https://dev.pokemontcg.io/
+
+Create one of the following files in the project root and add your key:
+- `.env.local` (recommended for Next.js)
+- `.env` (also supported)
+
+```bash
+# .env.local
+NEXT_PUBLIC_POKEMON_TCG_API_KEY=your_key_here
+```
+
+An example is provided in `.env.local.example`.
+
+### 4) Run the dev server
+```bash
+npm run dev
+```
+By default: http://localhost:3000
+
+If you see a server already running on port 3000, you can use another port:
+```bash
+PORT=3001 npm run dev
+```
+
+## Scripts
+- `npm run dev` – start Next.js in development
+- `npm run build` – production build
+- `npm run start` – start production server
+- `npm run lint` – lint project
+
+## Project Structure
+```
+magikarp-collection/
+├─ src/
+│  ├─ app/
+│  │  ├─ api/
+│  │  │  └─ magikarp/route.ts      # API route that fetches cards from Pokémon TCG API
+│  │  ├─ layout.tsx                # Root layout and global wrapper
+│  │  ├─ page.tsx                  # Main page: search, set filter, grid, checklist
+│  │  └─ globals.css               # Tailwind entry + global styles
+│  ├─ components/
+│  │  ├─ CardGrid.tsx              # Grid for card list
+│  │  ├─ CardItem.tsx              # Card tile with image, rarity, set badge, checklist toggle
+│  │  ├─ Header.tsx                # Title, search, stats
+│  │  ├─ SetBadge.tsx              # Shows set symbol and name
+│  │  └─ SetFilter.tsx             # Dropdown to filter by set
+│  ├─ lib/
+│  │  ├─ api.ts                    # Axios client for Pokémon TCG API
+│  │  └─ checklist.ts              # localStorage-backed checklist utils
+│  └─ types/
+│     └─ pokemon.ts                # TypeScript types for cards/sets
+├─ next.config.ts                  # Remote image domains, turbopack settings
+├─ tsconfig.json                   # TS config with path alias '@/*'
+├─ postcss.config.cjs              # Tailwind v4 PostCSS plugin config
+├─ package.json
+└─ .env.local.example              # Example env file
+```
+
+## Data Source
+- Pokémon TCG API v2: https://api.pokemontcg.io/
+  - Endpoint used: `GET /v2/cards` with query `q=name:magikarp`
+  - API key header: `X-Api-Key: <your key>` (automatically added when `NEXT_PUBLIC_POKEMON_TCG_API_KEY` is present)
+
+## How It Works
+- The client loads data from the internal Next.js route `GET /api/magikarp` (`src/app/api/magikarp/route.ts`).
+- The route proxies to the Pokémon TCG API using `fetchMagikarpCards()` (`src/lib/api.ts`).
+- Cards are displayed in `CardGrid`/`CardItem` with images and set symbols (`SetBadge`).
+- Checklist state is persisted locally via `localStorage` (`src/lib/checklist.ts`).
+
+## Deployment
+- **Vercel**: Zero-config for Next.js. Add `NEXT_PUBLIC_POKEMON_TCG_API_KEY` in project Environment Variables.
+- **Netlify/Other**: Build command `npm run build`, publish `.next` with a Next adapter or use Next on Node; make sure environment vars are set.
+
+## Troubleshooting
+- "Cannot find module '@tailwindcss/postcss'": install the Tailwind v4 PostCSS plugin and ensure CommonJS config.
+  ```bash
+  npm i -D @tailwindcss/postcss
+  # Ensure postcss.config.cjs exists with:
+  # module.exports = { plugins: { '@tailwindcss/postcss': {} } }
+  ```
+- Images not loading: confirm `next.config.ts` allows `images.pokemontcg.io` and restart the dev server.
+- No cards shown: ensure your API key is valid and in `.env.local` (or `.env`). Restart the dev server after changes.
+
+## License
+This project is provided as-is for personal collection tracking.