LivingDexTracker/data/pokemon/README.md

Pokémon Data (CSV Format)

This directory contains Pokémon data in CSV format for easy editing and maintenance.

File Structure

/data/pokemon/
├── gen1-kanto.csv          # Gen 1 Pokémon (Kanto region, #1-151)
├── gen2-johto.csv          # Gen 2 Pokémon (Johto region, #152-251) - Future
├── gen3-hoenn.csv          # Gen 3 Pokémon (Hoenn region, #252-386) - Future
├── games.csv               # All Pokémon games definitions
└── README.md               # This file

CSV Format

gen{N}-{region}.csv

One CSV file per generation/region containing all Pokémon from that generation.

Columns:

• pokedexNumber - National Pokédex number (e.g., 1, 25, 151)
• name - Pokémon name (e.g., Bulbasaur, Pikachu, Mew)
• form - Form name (empty for base form, "Female" for gender differences, "Alolan" for regional forms, etc.)
• games - Pipe-separated list of games where this Pokémon can be caught (e.g., "Red|Blue|Yellow")
• regionalNumber - Regional Pokédex number for base forms (empty for gender/alternative forms)

Example (gen1-kanto.csv):

pokedexNumber,name,form,games,regionalNumber
1,Bulbasaur,,Red|Blue|Yellow|LG: Pikachu|LG: Eevee,1
3,Venusaur,,Red|Blue|Yellow|LG: Pikachu|LG: Eevee,3
3,Venusaur,Female,Red|Blue|Yellow|LG: Pikachu|LG: Eevee,
25,Pikachu,,Red|Blue|Yellow|LG: Pikachu|LG: Eevee,25
151,Mew,,Red|Blue|Yellow,151

games.csv

Defines all Pokémon games.

Columns:

• id - Unique game identifier (lowercase, hyphenated, e.g., "red", "lg-pikachu")
• displayName - Display name for the game (e.g., "Red", "LG: Pikachu")
• region - Region/generation the game belongs to (e.g., "Kanto", "Johto")
• generation - Generation number (1-9)

Example:

id,displayName,region,generation
red,Red,Kanto,1
blue,Blue,Kanto,1
lg-pikachu,LG: Pikachu,Kanto,7

Editing with Excel/Google Sheets

CSV files are designed to be edited in spreadsheet applications:

1. Open the CSV file in Excel or Google Sheets
2. Use formulas, sorting, and filtering for bulk operations
3. Save as CSV when done

Example workflows:

Adding a new game to existing Pokémon

Find & Replace in the games column:

• Find: Red|Blue
• Replace: Red|Blue|NewGame

Adding a new Pokémon

Add a new row with all required fields:

152,Chikorita,,Gold|Silver|Crystal,1

Adding a regional form

Add a new row with the form name:

19,Rattata,Alolan,Sun|Moon|US|UM,

Generating SQL Migrations

After editing CSV files, generate SQL migrations using npm scripts:

# Generate migration for Kanto
npm run seed:kanto

# Generate migration for Johto (when ready)
npm run seed:johto

# Custom region
npm run seed:generate <RegionName>

Generated migrations will be created in /supabase/migrations/ with timestamp prefixes.

Testing Changes

After generating a migration:

# Reset local database to test
npm run supabase:reset

# Verify the changes loaded correctly

Important Notes

1. Regional Numbers: Only base forms (no form value) should have regionalNumber values. Forms like "Female" or "Alolan" should leave this column empty.

2. Game Names: Must exactly match the displayName in games.csv. Use pipe | as separator, no spaces around pipes.

3. National Dex Numbers: Must be accurate. Gender forms and regional variants share the same pokedexNumber as their base form.

4. CSV Encoding: Save files with UTF-8 encoding to support special characters.

5. Quotes: Only use quotes around values containing commas. Excel/Google Sheets handles this automatically.

Common Operations

Add a new generation (e.g., Gen 2 - Johto)

1. Create gen2-johto.csv with the format above
2. Add Johto games to games.csv
3. Run npm run seed:johto
4. Test with npm run supabase:reset

Add a new game to existing generation

1. Open games.csv, add new game row
2. Open the relevant gen{N}-{region}.csv file
3. Use Find & Replace to add the new game to the games column
4. Regenerate the migration: npm run seed:{region}
5. Test with npm run supabase:reset

Add DLC/expansion Pokémon

1. Add new Pokémon rows to the appropriate generation CSV
2. Update the games column with the DLC games
3. Regenerate the migration
4. Test

Database Schema

Generated migrations insert data into two tables:

• pokedex_entries: Pokémon species data (name, form, games, etc.)
• regional_dex_numbers: Regional Pokédex numbers (separate table for scalability)

This design allows adding new regions without database schema changes.