115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# 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.
|