Kanto Pokédex — Web Edition

A full-stack Pokémon collection and battle game covering the original 151 Kanto species plus 6 Dark-type additions for Psychic counterplay: browse the Pokédex, roll and collect your own Pokémon from lootboxes, evolve them, and battle them against AI or other players in real time — in English or Argentinian Spanish.

Play it: pokedex-next-rho.vercel.app (free account, email and password)

Unofficial, non-commercial fan project. Not affiliated with or endorsed by Nintendo, Game Freak or The Pokémon Company. See Disclaimer.

Features

• Pokédex — the 151 Kanto species plus 6 Dark-type additions (Umbreon; Houndour → Houndoom; Larvitar → Pupitar → Tyranitar — Psychic's only hard counter, added since Dark didn't otherwise exist in Kanto), 157 species total, with base stats, types, and moves.
• Collection — lootboxes roll a Pokémon with its own randomized stats and moveset, centered on (but independently varying from) its species' base stats, so no two of the same species are ever quite identical. Rare shiny rolls land near the top of what a species can roll. Lootboxes ("cases" in the UI) open on a CS2-style horizontal reel that spins toward the Pokémon the server already rolled, one at a time or up to five at once, with display-only rarity grades from each species' base stats.
• Battles — 3-on-3 team battles with switching, status effects (burn, poison, blind, freeze, bleed), and buff/debuff/drain/redirect moves layered on top of standard type-effectiveness damage:
  • Against AI — instant, solo, no opponent needed. Wins have a 60% chance to drop a lootbox.
  • Online PvP — create or join a room by code, battle another player's team live, with in-room chat and rematch support. Wins always drop a lootbox.
  • Move uses — every move can be cast a limited number of times per battle (max_uses), no regenerating resource pool. Each Pokémon always has at least one move — its weakest damage move, computed per battle — that's freely castable with no limit.
  • Every rolled or backfilled moveset guarantees 3 damage moves + 1 support move.
• Collection management — My Pokémon with per-Pokémon detail and a Select mode for Trade Up (burn 5 unwanted Pokémon for 1 guaranteed lootbox), Evolution (burn 5 same-species Pokémon for 1 guaranteed instance of its evolution, stats derived from the 5 burned instances rather than freshly rolled), and friend-to-friend trading.
• Social — friends list with invites, direct trading, a chat/message thread per friend, and a global leaderboard.
• Progress tracking — Home stat strip, match history, and in-app notifications.
• Starters — every new account picks one of Bulbasaur, Charmander, or Squirtle as a permanent starter (can't be traded or discarded) with a hand-authored moveset.
• Bilingual — English and Argentinian Spanish, toggled from the account menu alongside theme and sound; the whole app is translated (species/ move names and a handful of established jargon terms stay untranslated in both).

Tech stack

• Next.js 16 (App Router) + React 19 + TypeScript
• Supabase — Postgres database, Auth (email/password), Realtime broadcast
• No UI component library — hand-rolled design system (see design/DESIGN_SYSTEM.md)
• Vitest unit tests, SQL tests against a real Postgres, and GitHub Actions CI

How it works

flowchart LR
  B[Browser] -- "fetch /api/*" --> R[Next.js Route Handlers]
  R -- "secret key" --> DB[(Supabase Postgres)]
  B -- "publishable key: Auth" --> A[Supabase Auth]
  B <-- "private channels" --> RT[Supabase Realtime]
  R -- "broadcast" --> RT

• The server owns every game rule. Route Handlers check the session, re-check ownership in the same query, and resolve every battle round with the shared engine (lib/battleEngine.ts), for online rooms and bot battles alike. The browser only sends which move or switch the player chose; stats, results and rewards are never taken from the client.
• Multi-step writes are single transactions. Opening lootboxes, trades, trade-ups, evolutions, and ending a battle (lootbox plus match history) each run as one Postgres function, guarded so a round or a payout can only happen once even when two requests race.
• Online battles store each player's move until both are in, then resolve the round server-side and push the result over Realtime, with polling as the backstop. Neither player can see the other's move early.

Security model

• The browser holds only the publishable key, used for Auth and Realtime. The anon and authenticated roles have no privileges on any table and can execute no database function except the Realtime topic check, so the REST API can't be used to skip the app's checks.
• Route Handlers use the secret key, which bypasses RLS; RLS stays enabled on every table so a future grant is still deny-by-default.
• Realtime channels are private: a player can only join their own user: topic, friendships they're in, and rooms they play in. The only event a client may send is room chat.
• supabase/tests/database.sql checks all of the above on every CI run.

Getting started

Prerequisites

• Node.js and npm
• A Supabase project

Setup

1. Install dependencies:

   npm install
   

2. Copy the environment template and fill it in with values from your Supabase project's dashboard (Project Settings → API):

   cp .env.local.example .env.local
   

3. Apply the database schema. This project's migrations (supabase/migrations/*.sql) are written to run through Supabase's GitHub integration — connect your Supabase project to this repo and push to main, or apply them manually via the Supabase SQL editor in the order they're numbered.

4. Run the development server:

   npm run dev
   

   Open http://localhost:3000.

Other scripts

npm run build      # production build
npm run start      # run a production build
npm run lint       # eslint
npm run typecheck  # generate Next's route types, then tsc
npm test           # unit tests (Vitest)
npm run test:db    # SQL tests against the local Supabase database

Developing against a local Supabase instance

Real players use this app — no feature work happens directly against production. The workflow:

1. Work on a dedicated branch, never main directly, and don't push it until the whole wave is validated (see upgrades/'s own per-wave process). This keeps the branch — and anything Vercel or Supabase would otherwise auto-deploy from it — entirely local until you're ready.

2. Start a local Supabase stack (requires Docker Desktop running):

   npm run db:start   # supabase start -- pulls images on first run, then
                       # applies every migration in supabase/migrations/
                       # against a fresh local Postgres instance
   

   Other lifecycle commands: npm run db:stop, npm run db:status, npm run db:reset (wipes and replays every migration from scratch — the fast way to check a new migration applies cleanly).

3. Point .env.local at the values supabase status prints (API URL → NEXT_PUBLIC_SUPABASE_URL, anon key → NEXT_PUBLIC_SUPABASE_ PUBLISHABLE_KEY, service_role key → SUPABASE_SECRET_KEY) instead of your real project's. .env.local is gitignored, so this never touches what's deployed — back up your production values first if .env.local currently holds them (e.g. cp .env.local .env.local.production.bak, also gitignored) so switching back later is a copy, not a trip to the Supabase dashboard.

4. npm run dev as normal — now talking entirely to the local instance. Sign up a fresh test account (the handle_new_user trigger seeds starters the same way it does in production) rather than needing any special seed data.

5. Once every step in the wave is implemented and validated locally, merge to main locally and push — that single push is what triggers the real Supabase GitHub integration (migrations) and Vercel deploy (production code), only once, with everything already proven out.

Project structure

app/
  [lang]/              every page, under an EN/ES-AR URL segment (/en/...,
                        /es-AR/...)
    (app)/              authenticated screens (battle, inventory, pokedex,
                         dashboard, friends, online, leaderboard, etc.)
    login/, signup/     auth screens
  api/                 server routes (battles, rooms, friends, inventory,
                       ...) -- not under [lang]; Route Handlers don't render
                       user-facing text, so they don't need a locale
components/           React components, grouped by feature area
hooks/                shared React hooks
lib/                  business logic — battle engine, collection/roll
                       logic, evolution, Supabase clients, dashboard/
                       leaderboard/history queries
  i18n/                dictionaries (en.ts/es-AR.ts), getDictionary()
                       (Server Components) / useDictionary() (Client)
types/                shared TypeScript types (Pokémon, moves, battle state)
proxy.ts              session refresh, auth redirects and locale routing
                       (Next 16's renamed middleware)
tests/                unit tests (battle engine, action validation, bot
                       battles)
supabase/migrations/  versioned SQL schema, applied in order
supabase/tests/       SQL tests run against a migrated database
design/               design system spec and per-screen redesign tracker
upgrades/             this project's own step-by-step development log —
                       every feature wave is planned and tracked here
                       before it ships

Development process

This project tracks its own feature work in upgrades/: completed waves are archived under upgrades/archive/, and upgrades/main.md always reflects whatever's currently in progress (or says "no active wave" between them).

License

The code in this repository is released under the MIT License. The licence covers this project's own code only, not the Pokémon names, artwork or other material described below.

Disclaimer

Kanto Pokédex — Web Edition is an unofficial, non-commercial fan project made for learning and for fun. It is not affiliated with, endorsed, sponsored or approved by Nintendo, Game Freak, Creatures Inc. or The Pokémon Company.

Pokémon, the Pokémon names, characters, sprites and related marks are trademarks and copyrights of Nintendo, Game Freak, Creatures Inc. and The Pokémon Company. They are used here for non-commercial fan purposes only. Nothing in this project is sold, and no money changes hands: lootboxes are earned in game and cannot be bought.

If you are a rights holder and want something changed or removed, please open an issue or contact the author and it will be dealt with promptly.