Kanji Heatmap (previously Kanji Companion)
Development
nvm use 22
pnpm install
pnpm run dev # http://localhost:5174
pnpm run dev:cf is the same app on port 5173.
Note: Jisho, Jotoba, KanjiAPI and Google Handwriting lookups go through
Cloudflare Pages Functions (to get around CORS). Neither
dev script serves them, so they return 404 locally and only work on the
deployed site. Everything else works locally.
Data that isn't in the repo
The per-kanji vocabulary is one file per kanji, so it's gitignored. In
production it comes from cloud storage; locally the vocabulary sections of the
kanji drawer stay empty unless you fill these folders (paths are in
src/lib/assets-paths.ts):
public/kanji-words/v6/<KANJI>.jsonpublic/kanji-textbook-words-min/<KANJI>.json
The AI voice files (public/yomiage/, ~65 MB) aren't committed either.
pnpm dev and pnpm build copy them in with
scripts/copy-yomiage-files.mjs, downloading them once per yomiage version
into ~/.cache/yomiage. Offline, a dev server still starts and AI Voice Mode
falls back to the browser voice; a CI build fails instead.
Everything else the app fetches is committed.
Checks
These are what CI runs (.github/workflows/ci.yml):
pnpm run format:check # fix with: pnpm exec prettier --write <file>
pnpm run lint
pnpm run typecheck
pnpm test
CF_PAGES=1 pnpm run build
CF_PAGES=1 turns off the Cloudflare Vite plugin, matching the real Cloudflare
Pages build. pnpm run build does not run Prettier, so run format:check
yourself.
End-to-end tests (Playwright)
pnpm install doesn't download browsers. Install Chromium once, and again
after Playwright upgrades:
pnpm exec playwright install chromium
pnpm test:e2e
To watch or debug a run, add --headed, --debug or --ui to
pnpm exec playwright test. If a run fails with
browserType.launch: Executable doesn't exist, install Chromium again.
Kanji data
Every data file the app fetches (public/json/v2/, public/json/katakana/,
public/json/fill-the-kanji/, public/svg/) and the Fill the Kanji files in
src/lib/fill-the-kanji/ (chunking.json, set-sizes.json,
set-chunks.json) are generated by a separate data build and committed here.
Never edit them by hand: a data change is made in the data build, and its
output is copied over these files.
In Fill the Kanji, a batch is cut from the set in file order, so a data change
that inserts or deletes sentences in the middle of a set moves sentences into
different batches, and players' stats stay with the batch numbers, not the
sentences.
File sizes
./scripts/print-file-sizes.sh
prints raw and gzipped sizes.
Build analysis
ANALYZE=true ANALYZE_TEMPLATE=flamegraph pnpm run build
# ANALYZE_TEMPLATE: sunburst, treemap, network, raw-data, list or flamegraph
The visualizer settings are in vite.config.ts.
Talk to us
