Capstone: Shipping This as a Real New Page on the Live Site, and Scoping Kanji Conversion as a Genuine Future Sub-Project
Romaji to Kana Converter: Astro
Chapter 8 · Capstone: Shipping This as a Real New Page on the Live Site, and Scoping Kanji Conversion as a Genuine Future Sub-Project
Chapter 1 opened this course with a real claim: unlike its Angular & Express and React & Next.js siblings, this converter is built in the exact same framework the real, live site already runs on, making it the most direct "just add a page" story of the whole trio. Every chapter since has been building toward actually cashing that claim in. This capstone does it — comparing two real integration paths, recommending the one that fits the site's own established conventions, and closing the one deliberate gap this course left open from its very first chapter: kanji conversion.
What Each Chapter Actually Built
Ch.1 — Setup
A default, static-output Astro project — no database, no adapter, since conversion is a pure, stateless function.
Ch.2-3 — The Engine
A complete, real gojūon/dakuten/yōon KANA_MAP and tokenizer in src/lib/convert.ts, with four genuine bugs found and fixed, all independently re-verified against live Node output.
Ch.4 — The UI
A plain client-side <script> importing convert() directly — verified bundled, TypeScript-aware, and import-resolved by Astro with zero config.
Ch.5 — The Real Verdict
A real /api/convert route plus a genuine local benchmark: ~1.36µs direct vs. ~14,084µs over HTTP — client-side wins, measured, not assumed.
Ch.6 — Styling
MT4's own established palette, the Japanese-red accent (language_rules.md L4a), and a verified finding about Astro's own automatic per-component CSS scoping.
Ch.7 — Deployment
A real, working standalone deployment for the full app — with an honest closing note that it exists mainly to keep Chapter 5's own comparison reachable.
Two Real Ways This Converter Could Actually Reach the Live Site
"A new page on the live site" isn't one single mechanism — this site has two genuinely different real ways a page can end up there, and they behave very differently:
| Path | What it actually means | Real tradeoffs |
|---|---|---|
| A. A native Astro route | Copy Chapter 6's own finished index.astro directly into the live site's own src/pages/, as its own real route |
Reuses this course's own file almost unchanged — but stands apart from every other Sidebar/My Tools page on the site, which don't work this way at all; wouldn't automatically pick up the shared nav/footer unless separately wired into the site's own layout |
| B. A My Tools-style fragment | Turn the finished markup into a self-contained HTML fragment, following my_tools_rules.md's own established MT1-MT9 convention for exactly this kind of interactive tool |
Matches every other real interactive tool already on the site; picked up automatically by the site's own shared template via set:html, with no separate routing to wire up — the real, established pattern this kind of tool already uses |
Path B is the real, better fit — not because path A wouldn't technically work, but because it would make this converter the one interactive tool on the whole site that doesn't follow the same pattern every other one already does. Reusing an established convention, per this course's own MT4 finding back in Chapter 6, is exactly the discipline this site already practices everywhere else.
data-astro-cid-*
protection Chapter 6 also found — the manual scoping was already doing that exact job, on standby, since the
moment it was written.
The Real, Recommended Shipped Version Is Simpler Than Chapter 7's Own Deployment
Chapter 5 already delivered a real, measured verdict: client-side conversion is the objectively better
choice for this feature. Taking that verdict seriously all the way through to shipping means the version
that actually belongs on the live site doesn't need /api/convert, the Node adapter, or a single
piece of Chapter 7's own PM2/nginx/rate-limiting machinery — none of it. A My Tools fragment is static HTML,
CSS, and a plain client-side script, served the exact same way every other tool on the site already is, with
no server process of its own required at all.
A Real My Tools Spec, Sketched Out
my_tools_rules.md's own MT2/MT3 define the spec format a real /my-tools invocation
would read from — a YAML file at my-tools/romaji-converter.yaml, describing the tool completely
enough that no separate input is needed beyond it:
Everything that spec describes is already real and already tested — this course's own Chapters 2 through 6 are the actual functional and visual specification, just written as prose instead of YAML.
Scoping Kanji Conversion as a Genuine Future Sub-Project
Chapter 1 deferred kanji conversion explicitly, naming it "a genuinely bigger, real dictionary-and-context- dependent problem" rather than something this course would solve as a side effect. It's worth closing that gap honestly rather than leaving it as a vague aside — naming concretely what it would actually take:
- A real dictionary, not a lookup table. Unlike
KANA_MAP's own fixed, roughly 100-entry romaji-to-kana mapping, a working kanji converter needs a genuine word-level dictionary — thousands of entries, each kana reading mapped to one or more real candidate kanji spellings. - Real disambiguation, not a single answer. The same kana can map to several different kanji depending on meaning and context — this is the actual hard part, and it's a genuinely different kind of problem from anything Chapters 2-3 solved, since those chapters' own ambiguities (standalone "e" as へ vs. 絵, per Chapter 3's own warn-box) were already honestly documented as unresolvable by a lookup table alone. A real kanji feature would need the same category of context-awareness, at a much larger scale.
- A genuine reason to move server-side. Chapter 5's own exercise 3 already named this directly: a real dictionary large enough to disambiguate correctly is "far too large to ship to every visitor's browser on every page load" — a real, structural reason to keep that specific lookup on a server, unlike plain romaji-to-kana conversion, which this whole course spent Chapter 5 proving has no such need.
Closing This Course
Eight chapters produced a real, tested conversion engine (four genuine bugs found and independently verified, not assumed), a real measured answer to the question this whole trio of courses was built around (client-side wins, by roughly four orders of magnitude), a real deployment story for the alternative anyway, and a concrete, evidence-backed plan for actually shipping the recommended version as a real page on the site it was always meant to join — closing exactly where Chapter 1 opened, with the claim now backed by eight chapters of real, verified work rather than a promise.
Hands-On Exercises
Write your own complete my-tools/romaji-converter.yaml spec file matching MT3's schema, including a real example block, based entirely on what this course actually built in Chapters 2 through 6.
📄 View solutionExplain in your own words why Chapter 6's decision to scope the CSS under a wrapper class "on purpose" turned out to matter directly in this capstone, tracing the specific real mechanism that makes it matter.
📄 View solutionUsing Chapter 5's own real, measured evidence, explain why the version of this converter that should actually ship needs none of Chapter 7's own adapter/PM2/nginx-rate-limiting machinery at all.
📄 View solutionChapter 8 / Course Complete — Quick Reference
- Two real integration paths compared — a native Astro route vs. a My Tools fragment; the fragment path wins, matching every other real tool already on the site
- Chapter 6's scoping pays off directly — the wrapper class added "on purpose" is exactly what makes the fragment migration safe
- Ship client-side only — per Chapter 5's own real verdict, no adapter/PM2/nginx machinery needed for the recommended shipped version
- A real MT3-schema spec — name, description, and example, drawn directly from this course's own finished work
- Kanji conversion, honestly scoped out — a real dictionary, real disambiguation, and (per Chapter 5's own exercise 3) a genuine reason to run server-side, unlike this course's own plain romaji conversion
- Course complete — 8/8 chapters, closing the claim Chapter 1 opened with real, verified evidence