Shiritori (Japanese)

A static React + TypeScript web app for solo Japanese shiritori.

This repository is open source under the MIT license. See LICENSE for the code license and NOTICE.md for third-party data attribution and redistribution notes.

Features

• Player vs AI gameplay (dictionary-backed validation)
• Input field with automatic romaji-to-kana conversion via wanakana.js (Shift/uppercase for katakana)
• Configurable per-word timer (default 10s, range 5-30s)
• Optional no-timer mode with manual end-game control
• Rule toggles for normalization and repeat handling
• Light/Dark/System theme preference with persistent override
• Local persistence for settings and aggregate stats
• JMdict attribution page

Tech Stack

• React 18 + TypeScript + Vite
• Vitest + Testing Library
• Static deployment target: Vercel

Project Structure

• src/lib/kana.ts: input canonicalization + kana boundaries
• src/lib/validator.ts: player-word validation logic
• src/lib/ai.ts: AI move selection
• src/lib/dictionary.ts: dictionary loading/indexing
• src/lib/storage.ts: localStorage persistence (versioned keys)
• src/game/state.ts: reducer/state transitions
• src/components/*: gameplay/settings/stats/history UI
• src/pages/AboutAttribution.tsx: JMdict/EDRDG credits
• scripts/build-dictionary.ts: JMdict-to-playlist build pipeline
• public/data/*.json: prebuilt dictionary assets shipped to the browser

Local Development

1. Install dependencies:

npm install

2. Start dev server:

npm run dev

3. Run tests:

npm test

4. Build production bundle:

npm run build

Dictionary Build Pipeline (JMdict)

The app ships with generated dictionary assets in public/data/.

To rebuild from JMdict:

1. Place JMdict files in public/data/raw/ (default input: public/data/raw/JMdict_e).
2. Run:

npm run dict:build

Optional flags:

npm run dict:build -- --input public/data/raw/JMdict_b --output-dir public/data --min-length 2
npm run dict:build -- --include-all
npm run dict:build -- --pos-filter all

Default behavior:

• filters to noun entries only (--pos-filter noun, default)
• filters to common-priority entries (news/ichi/spec/gai tags)
• writes public/data/dictionary.v1.json and public/data/index-by-start.v1.json

Deployment (Vercel)

1. Import this repo into Vercel.
2. Build command: npm run build
3. Output directory: dist
4. Optionally add a custom domain for your own deployment.
5. Configure DNS records in your DNS provider as prompted by Vercel.

vercel.json includes:

• SPA rewrite for client-side routing
• Cache headers for dictionary JSON assets under /data/*

Open Source Notes

• Code license: MIT
• Dataset attribution and redistribution notes: see NOTICE.md
• Security reporting: see SECURITY.md
• Contribution guide: see CONTRIBUTING.md

Attribution

• JMdict / EDRDG: https://www.edrdg.org/jmdict/j_jmdict.html
• EDRDG: https://www.edrdg.org/