226 lines
5.3 KiB
Markdown
226 lines
5.3 KiB
Markdown
# Pokedex Online
|
|
|
|
A modern React + Vite web application for exploring comprehensive Pokémon data with advanced search, filtering, and comparison tools.
|
|
|
|
## 🌟 Status
|
|
|
|
**✅ Production Ready** - All 106 tests passing, fully functional.
|
|
|
|
See [PROGRESS.md](PROGRESS.md) for detailed development status.
|
|
|
|
## Features
|
|
|
|
- **Advanced Search** - Find Pokémon by name with autocomplete (optimized with Web Workers)
|
|
- **Detailed Info Cards** - Complete stats, moves, abilities, and evolution chains
|
|
- **Type Effectiveness** - Interactive matrix showing type matchups
|
|
- **Comparison Tool** - Compare multiple Pokémon side-by-side
|
|
- **Smart Filtering** - Filter by type, generation, stats, and abilities
|
|
- **Dark Mode** - Full theme support with system preference detection
|
|
- **Bookmarks** - Save favorite Pokémon for quick access
|
|
- **Responsive Design** - Optimized for mobile, tablet, and desktop
|
|
- **Fast Performance** - Lazy loading, code splitting, and efficient caching
|
|
- **Accessible** - WCAG 2.1 Level AA compliance, keyboard navigation
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- npm
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development server
|
|
npm run dev
|
|
|
|
# Open browser to http://localhost:5173
|
|
```
|
|
|
|
### Development Commands
|
|
|
|
```bash
|
|
# Development with hot reload
|
|
npm run dev
|
|
|
|
# Production build
|
|
npm run build
|
|
|
|
# Preview production build
|
|
npm preview
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Run tests with UI
|
|
npm run test:ui
|
|
|
|
# Generate coverage report
|
|
npm run test:coverage
|
|
```
|
|
2. **Option 2: Environment-based** - Create `.env` file (see Environment Setup section below) for CI/CD or shared development
|
|
|
|
### Environment Setup (Optional)
|
|
|
|
If you prefer environment variables:
|
|
|
|
```bash
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
|
|
# Edit .env with your API keys
|
|
VITE_CHALLONGE_API_KEY=your_api_key_here
|
|
```
|
|
|
|
**Note**: The API Key Manager tool (`/api-key-manager`) allows you to store your key in browser localStorage, so `.env` configuration is now optional.
|
|
|
|
```bash
|
|
# Build the app
|
|
npm run build
|
|
|
|
# Preview production build
|
|
npm run preview
|
|
```
|
|
|
|
## 🐳 Docker Deployment
|
|
|
|
```bash
|
|
# Build and run with Docker Compose
|
|
docker-compose up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# Stop services
|
|
docker-compose down
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
src/
|
|
├── components/ # React components
|
|
│ ├── PokemonCard.jsx
|
|
│ ├── SearchBar.jsx
|
|
│ ├── TypeMatrix.jsx
|
|
│ └── ...
|
|
├── hooks/ # Custom React hooks
|
|
│ ├── usePokemon.js
|
|
│ ├── useSearch.js
|
|
│ └── ...
|
|
├── services/ # API & data services
|
|
│ ├── pokemonService.js
|
|
│ ├── typeService.js
|
|
│ └── ...
|
|
├── utils/ # Helper functions
|
|
│ ├── formatters.js
|
|
│ ├── validators.js
|
|
│ └── ...
|
|
├── types/ # TypeScript type definitions
|
|
│ └── pokemon.ts
|
|
├── styles/ # Global styles
|
|
│ └── index.css
|
|
├── workers/ # Web Workers
|
|
│ └── search.worker.js
|
|
├── App.jsx
|
|
└── main.jsx
|
|
|
|
test/
|
|
├── unit/ # Unit tests
|
|
├── integration/ # Integration tests
|
|
└── e2e/ # End-to-end tests
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
Comprehensive test coverage with Vitest:
|
|
|
|
```bash
|
|
# Run tests once
|
|
npm run test:run
|
|
|
|
# Run tests in watch mode
|
|
npm test
|
|
|
|
# Open test UI
|
|
npm run test:ui
|
|
|
|
# Generate coverage report
|
|
npm run test:coverage
|
|
```
|
|
|
|
**106 tests** covering:
|
|
- Services and utilities (unit tests)
|
|
- Component integration
|
|
- User workflows
|
|
- Edge cases and error handling
|
|
|
|
### Tournament Manager (Coming Soon)
|
|
- Manage Challonge tournaments
|
|
- Add/remove participants
|
|
- Submit match scores
|
|
- Track tournament progress
|
|
|
|
## 🔑 API Keys & Configuration
|
|
|
|
### Challonge API
|
|
1. Create account at https://challonge.com
|
|
2. Get API key from https://challonge.com/settings/developer
|
|
3. Add to `.env`:
|
|
```
|
|
VITE_CHALLONGE_API_KEY=your_key_here
|
|
```
|
|
|
|
### Environment Variables
|
|
All environment variables must be prefixed with `VITE_` to be available in the browser:
|
|
|
|
```bash
|
|
# ✅ Correct - Available in browser
|
|
VITE_CHALLONGE_API_KEY=abc123
|
|
|
|
# ❌ Wrong - Not accessible
|
|
CHALLONGE_API_KEY=abc123
|
|
```
|
|
|
|
Access in code:
|
|
```javascript
|
|
const apiKey = import.meta.env.VITE_CHALLONGE_API_KEY;
|
|
```
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
- **Vue 3.4** - Progressive JavaScript framework with Composition API
|
|
- **Vue Router 4** - Official routing library
|
|
- **Vite 5** - Next generation frontend tooling
|
|
- **Docker** - Containerization
|
|
- **nginx** - Web server for production
|
|
|
|
## 📚 Documentation
|
|
|
|
- [PROJECT_PLAN.md](./PROJECT_PLAN.md) - Complete implementation roadmap
|
|
- [GAMEMASTER_IMPLEMENTATION.md](./GAMEMASTER_IMPLEMENTATION.md) - Gamemaster feature details
|
|
- [Vue 3 Docs](https://vuejs.org/)
|
|
- [Challonge API](https://api.challonge.com/v1)
|
|
|
|
## 🔒 Security Notes
|
|
|
|
- **Never commit `.env`** - Contains sensitive API keys
|
|
- **Use environment variables** - All configs in `.env`
|
|
- **Prefix with VITE_** - Required for browser access
|
|
- **Keep API keys private** - Don't share in public repos
|
|
|
|
## 🔗 Related Apps
|
|
|
|
- **apps/** - Additional apps accessible at app.pokedex.online
|
|
|
|
## 📝 Development Notes
|
|
|
|
This project uses:
|
|
- Vue 3 Composition API with `<script setup>`
|
|
- Vite for fast HMR and optimized builds
|
|
- Multi-stage Docker builds for minimal image size
|
|
- nginx:alpine for production serving
|