68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# Pokédex PWA
|
||
|
||
A responsive, offline-capable Pokédex reference built on
|
||
[PokéAPI](https://pokeapi.co/). Vanilla JS + Vite + Workbox — no UI
|
||
framework.
|
||
|
||
## Two headline features
|
||
|
||
| Feature | How it works |
|
||
| --- | --- |
|
||
| **Game series selection** | Pick a *game* (PokéAPI version group, e.g. Scarlet & Violet). If it has more than one regional dex (Paldea / Kitakami / Blueberry) a sub-dex switcher appears. The choice drives which species show, their regional numbering, and which version's flavor text the detail page uses. Stored in `localStorage`. |
|
||
| **Unified Pokémon selection** | One tracking record per Pokémon, keyed by **National Dex id**. Mark Pikachu once and every game's view reflects it — each dex computes its own "Seen / Caught" totals by intersecting its species list with that single map. The active Pokémon is also a single deep-linkable route (`#/pokemon/25`). |
|
||
|
||
## Data & storage split
|
||
|
||
- **Preferences + tracking state** → `localStorage` (`pdx.settings`, `pdx.selection`). Tiny, synchronous, restored on reload.
|
||
- **Build-time snapshot** (`src/data/snapshot.json`, ~150 KB) → generated by `npm run snapshot` from PokéAPI: every species (id, name, generation, types), all regional Pokédex lists, and all version groups. Precached by the service worker, so the list / search / game switching work on the first offline launch.
|
||
- **Detail data** (stats, abilities, flavor text, evolution) → fetched lazily from `pokeapi.co` per Pokémon, then cached by the service worker (stale-while-revalidate, 30-day TTL).
|
||
- **Sprites** → cache-first with a capped LRU.
|
||
|
||
Export / import of `settings` + `selection` as JSON lives in **Settings**.
|
||
|
||
## Scripts
|
||
|
||
```bash
|
||
npm install
|
||
npm run snapshot # fetch data from PokéAPI -> src/data/snapshot.json (run once; refreshes if >30 days old)
|
||
npm run dev # vite dev server
|
||
npm run build # runs snapshot (prebuild) then vite build
|
||
npm run preview # serve the production build (needed to exercise the service worker)
|
||
```
|
||
|
||
Deploying under a sub-path (e.g. GitHub Pages project site): `BASE_PATH=/repo-name/ npm run build`.
|
||
|
||
## Project layout
|
||
|
||
```
|
||
scripts/build-snapshot.mjs PokéAPI -> snapshot.json
|
||
src/
|
||
main.js boot: theme, nav, router, SW registration
|
||
router.js hash router (#/, #/pokemon/:id, #/games, #/search, #/settings)
|
||
sw.js Workbox service worker (injectManifest)
|
||
store/ createStore + settings + selection (localStorage)
|
||
data/ snapshot loader, pokedex resolver, lazy API client
|
||
components/ Card, Sprite, TypeChip, StatBar, ProgressHeader, Nav
|
||
views/ DexGrid, PokemonDetail, GamePicker, SearchView, SettingsView
|
||
styles/ tokens.css (palette, type colors, light/dark), layout.css
|
||
```
|
||
|
||
## Status
|
||
|
||
Scaffold — build steps 1–5 of the design are in place: responsive shell,
|
||
snapshot pipeline, dex grid with per-dex progress, game picker, lazy detail
|
||
page, offline search, settings with export/import, and the service worker.
|
||
|
||
Not yet done: evolution chain, version-exclusive badges, richer filters
|
||
(type/generation/legendary — the snapshot would need legendary flags),
|
||
skeleton loaders, install-prompt handling, PNG/maskable raster icons
|
||
(currently an SVG icon only), and a Lighthouse PWA pass.
|
||
|
||
## Notes
|
||
|
||
- `npm audit` reports the known esbuild dev-server advisory via Vite 5. It
|
||
affects the local dev server only, not the production build. Vite 8 (which
|
||
fixes it) requires a newer Node than this environment has.
|
||
- Data and images © Nintendo / Game Freak / The Pokémon Company, served via
|
||
PokéAPI. This project is a non-commercial reference tool.
|