DEV Community

Cover image for How I Built a Wordle for Chinese Idioms with 7,200+ Words, Pinyin & Audio (and achieved a 100 Lighthouse score)
Fedora
Fedora

Posted on

How I Built a Wordle for Chinese Idioms with 7,200+ Words, Pinyin & Audio (and achieved a 100 Lighthouse score)

#javascript #opensource #showdev #webdev

Hey everyone! 👋

I'm excited to share a side project I've been building and optimizing recently: EasyIdiom (成语猜词) — a free, daily word puzzle game that brings the engaging mechanics of Wordle to traditional 4-character Chinese idioms (成语, chéngyǔ).

🎮 Live Game: https://easyidiom.com/

⭐ GitHub Repository: https://github.com/fds2003/easyidiom

🎯 The Motivation

Wordle took the world by storm, but adapting it to Chinese characters presented unique linguistic and technical challenges:

  1. Chinese is not based on an alphabet — each idiom consists of 4 distinct characters with individual tones and pronunciations (Pinyin).
  2. Beginners and language learners often know the pronunciation or meaning without knowing how to type complex strokes.
  3. How to provide progressive feedback (character correctness, pinyin accuracy, and cultural definitions) without spoiling the game?

🛠️ The Tech Stack

To keep the web app lightning fast on mobile devices without bloated frameworks:

  • Frontend Core: Preact (3kB lightweight alternative to React) + Vite
  • Phonetic Engine: pinyin-pro for dynamic tone generation & polyphone handling
  • Sound Effects: Lightweight Web Audio API & Howler.js for tactile keypress feedback
  • Analytics & Screen Recording: Interaction-deferred Google Analytics 4 & Microsoft Clarity (zero CWV impact)
  • Deployment & Hosting: Global Edge CDN via Vercel with zero cold starts

⚡ Key Engineering & Optimization Challenges

1. Pinyin Feedback & Algorithmic Clues

Unlike English 5-letter words, Chinese idioms have dual layers: Hanzi (Character) and Pinyin (Pronunciation).
We built an interactive virtual keyboard that aggregates pinyin initials and finals dynamically based on candidate idioms, highlighting:

  • 🟩 Green: Exact character & position match.
  • 🟧 Amber: Character exists in the idiom but in a different position.
  • ⬜ Gray: Character is absent from the target idiom.

2. Zero-Runtime Dead Code & 100/100 Lighthouse Performance

By auditing JavaScript chunks:

  • Replaced heavyweight polyfills and font dependencies with modern native system font stacks (system-ui, -apple-system, Segoe UI...), reducing font payload from 1,600ms latency down to 0ms.
  • Dynamic import() splitting for heavy visual tools (e.g., canvas-confetti and html-to-image).
  • Deferred third-party trackers until first user interaction (pointerdown, keydown, scroll), achieving a flawless 100/100 Core Web Vitals score on Mobile & Desktop.

3. Progressive Clue Engine ("I'm Stuck")

For learners stuck on difficult idioms, we implemented a 3-tier clue system:

  1. 1st Click: Displays cultural/dictionary definition hints without revealing words.
  2. 2nd Click: Reveals the pinyin & tone of the 1st character.
  3. 3rd Click: Reveals a mystery character location.

🚀 Try It Out & Feedback!

The game is 100% free, requires no sign-up, and works offline/on mobile.

I'd love to hear your thoughts, UI suggestions, or ideas for new features! If you find it helpful for learning Chinese or testing your puzzle skills, a ⭐ on GitHub would mean the world!

Happy guessing! 🐯🎉

Top comments (0)