Skip to content

jayk0001/pokedex

BranchesTags

Repository files navigation

🎮 Pokédex - Full-Stack Pokemon Explorer

A modern, feature-rich Pokédex application built with Next.js 15, featuring user authentication, favorites system, advanced search, and comprehensive Pokemon details.

Next.js React TypeScript tRPC Prisma Tailwind CSS

✨ Features

🔍 Pokemon Exploration

  • Paginated Pokemon List - Browse through 1300+ Pokemon with smooth pagination
  • Advanced Search - Debounced search with case-insensitive matching
  • Type Filtering - Filter Pokemon by any of the 18 types
  • Detailed Pokemon View - Comprehensive stats, abilities, types, and artwork

👤 User Authentication

  • Secure Registration/Login - Email/password authentication with Better Auth
  • Session Management - Persistent login sessions with automatic cleanup
  • Protected Routes - Seamless authentication flow with redirect preservation

❤️ Favorites System

  • Personal Collection - Save favorite Pokemon to your personal list
  • Optimistic UI - Instant visual feedback with background persistence
  • Dedicated Favorites Page - View and manage your collection with pagination
  • Cross-Page Sync - Favorite status consistent across all pages

🎨 User Experience

  • Responsive Design - Perfect on desktop, tablet, and mobile
  • Dark Mode Support - System-aware theme switching
  • Loading Skeletons - Professional loading states
  • Error Handling - Graceful error recovery with helpful messages
  • Smooth Animations - Micro-interactions and hover effects

🛠️ Tech Stack

Frontend Framework

  • Next.js 15.5.3 - Latest React framework with App Router
  • React 19.1.0 - Latest React with concurrent features
  • TypeScript - Type safety and developer experience

Styling & UI

  • Tailwind CSS - Utility-first CSS framework for rapid development
  • CSS Modules - Component-scoped styling
  • Responsive Design - Mobile-first approach with breakpoints

State Management & API

  • tRPC 11.5.1 - End-to-end typesafe APIs
  • React Query - Powerful data fetching and caching
  • Zod - Schema validation and type inference

Database & ORM

  • Prisma 6.16.1 - Next-generation ORM with type safety
  • SQLite - Lightweight database for development
  • Better Auth - Modern authentication solution

External APIs

  • PokéAPI - Comprehensive Pokemon data source
  • RESTful Integration - Efficient data fetching and caching

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • npm, yarn, or pnpm

Installation

  1. Clone the repository
git clone <repository-url>
cd pokedex-starter
  1. Install dependencies
npm install
# or
yarn install
# or
pnpm install
  1. Set up the database
npx prisma db push
  1. Start the development server
npm run dev
# or
yarn dev
# or
pnpm dev
  1. Open the application Visit http://localhost:3000 in your browser.

📱 Usage Guide

Registration & Login

  1. Click "Register" in the navigation bar
  2. Fill in your email and password (minimum 6 characters)
  3. After registration, you'll be automatically logged in
  4. Use "Login" for returning users

Exploring Pokemon

  1. Browse: Use pagination to explore all Pokemon
  2. Search: Type Pokemon names in the search bar (debounced for performance)
  3. Filter: Use the "Filter By" dropdown to filter by type
  4. Details: Click any Pokemon card to view detailed information

Managing Favorites

  1. Add to Favorites: Click the heart icon on any Pokemon card or detail page
  2. Remove from Favorites: Click the filled heart icon to remove
  3. View Collection: Click "Favorites" in the navigation (requires login)
  4. Authentication: Non-logged users are prompted to login and returned to their previous context

Pokemon Detail Page

  • High-Quality Artwork: Official Pokemon artwork
  • Comprehensive Stats: HP, Attack, Defense, Sp. Attack, Sp. Defense, Speed
  • Type Information: Color-coded type badges
  • Abilities: Including hidden abilities
  • Physical Stats: Height and weight in metric units
  • Base Experience: Training value

🏗️ Project Architecture

Directory Structure

src/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   ├── favorites/         # Favorites page
│   ├── login/            # Authentication pages
│   ├── pokemon/[name]/   # Dynamic Pokemon detail pages
│   └── page.tsx          # Home page
├── components/           # Reusable React components
│   ├── favorite-button.tsx
│   ├── navigation.tsx
│   └── providers.tsx
├── lib/                 # Utility libraries
│   ├── auth.ts         # Authentication configuration
│   ├── auth-client.ts  # Client-side auth hooks
│   └── db.ts           # Database connection
├── server/             # Server-side code
│   └── api/           # tRPC routers
│       ├── routers/   # API route handlers
│       └── root.ts    # API router configuration
└── utils/             # Shared utilities
    └── trpc.ts        # tRPC configuration

Key Libraries & Their Purpose

tRPC (Type-Safe APIs)

  • Why: End-to-end type safety from backend to frontend
  • Benefits: Eliminates API documentation needs, catches errors at compile time
  • Usage: Pokemon data fetching, favorites management

Prisma (Database ORM)

  • Why: Type-safe database operations with excellent developer experience
  • Benefits: Auto-generated types, migration management, query optimization
  • Usage: User management, favorites storage

Better Auth (Authentication)

  • Why: Modern, secure authentication with minimal setup
  • Benefits: Built-in security best practices, session management
  • Usage: User registration, login, session handling

React Query (Data Fetching)

  • Why: Powerful caching, background refetching, optimistic updates
  • Benefits: Automatic loading states, error handling, cache invalidation
  • Usage: Pokemon API calls, favorites synchronization

Zod (Schema Validation)

  • Why: Runtime type validation with TypeScript integration
  • Benefits: API input validation, type inference
  • Usage: Form validation, API schema definition

🎯 API Endpoints

Pokemon Routes (/api/pokemon)

  • getList - Paginated Pokemon list with search and type filtering
  • getByName - Individual Pokemon details by name

Favorites Routes (/api/favorites)

  • add - Add Pokemon to user favorites
  • remove - Remove Pokemon from favorites
  • isFavorited - Check if Pokemon is favorited
  • getUserFavorites - Get user's favorite Pokemon with pagination
  • getFavoritesCount - Get total favorites count

Authentication Routes (/api/auth)

  • Registration, login, logout, session management

🔄 Data Flow

Pokemon Data

  1. Source: PokéAPI (https://pokeapi.co/)
  2. Caching: React Query for client-side caching
  3. Processing: Server-side data transformation and optimization
  4. Delivery: tRPC for type-safe data transfer

User Authentication

  1. Registration/Login: Better Auth handles secure authentication
  2. Session: Persistent sessions with automatic refresh
  3. Protection: Route-level authentication with redirect preservation

Favorites System

  1. Optimistic Updates: UI updates immediately
  2. Background Sync: API calls persist changes
  3. Cache Invalidation: Automatic data refresh across pages
  4. Real-time Sync: Consistent state across all components

🚀 Performance Optimizations

Frontend Optimizations

  • Code Splitting: Automatic route-based splitting
  • Image Optimization: Next.js automatic image optimization
  • Caching Strategy: React Query with intelligent cache invalidation
  • Debounced Search: 300ms delay prevents excessive API calls

Backend Optimizations

  • Batch Requests: Multiple Pokemon details fetched in parallel
  • Database Indexing: Optimized queries for favorites
  • Response Caching: Efficient data transformation

User Experience

  • Loading Skeletons: Perceived performance improvement
  • Optimistic UI: Immediate feedback for user actions
  • Error Boundaries: Graceful error handling

🌟 Future Enhancements

Planned Features

  • Advanced Filtering: Multiple simultaneous filters
  • Pokemon Comparison: Side-by-side stat comparison
  • Team Builder: Create and manage Pokemon teams
  • Battle Calculator: Type effectiveness and damage calculation
  • Social Features: Share favorites and teams
  • Offline Mode: PWA capabilities for offline browsing

Technical Improvements

  • Database Migration: PostgreSQL for production
  • Image CDN: Optimized Pokemon image delivery
  • Search Enhancement: Elasticsearch for advanced search
  • Analytics: User behavior tracking
  • Testing: Comprehensive test suite

📝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • PokéAPI - Comprehensive Pokemon data
  • Next.js Team - Amazing React framework
  • Tailwind CSS - Utility-first CSS framework
  • tRPC Team - Type-safe API development
  • Prisma Team - Modern database toolkit

Built with ❤️ using modern web technologies

About

Pokédex - Full-Stack Pokemon Explorer

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages