Behind the Build
Building Wordle: From Daily Habit to Side Project
How a game I couldn’t stop playing became the first project on this site.
I was looking for a small coding project. Not something that would take months to finish or require a pitch deck to explain — just something compact that I could build from scratch and put somewhere to say “hey, I can code, and I actually like doing it.”
The answer was already part of my daily routine. I’d been playing Wordle every day — the kind of game that takes five minutes but lives in your head for the next hour. I liked it enough that I wanted more of it, and the best way I knew how to get more of something was to build it myself. It felt right as a project: something I genuinely enjoyed, not something contrived for a recruiter’s benefit.
Starting with Python and the Terminal
The first version was a Python script that ran in the terminal. No UI, no frameworks — just the raw game loop. You type a five-letter word, and it prints back colored squares. Green for correct, yellow for wrong position, gray for not in the word. The core algorithm is surprisingly interesting to get right.
The tricky part is handling duplicate letters. Say the word is APPLE and you guess PEPPY. Both have the letter P in multiple positions, but you can’t just loop through and mark every matching letter as “present” — you need to respect how many times that letter actually appears in the target word. My implementation uses a two-pass approach:
// First pass: mark exact matches (green)
for (let i = 0; i < guess.length; i++) {
if (guess[i] === word[i]) {
results[i] = { letter: guess[i], state: 'correct' };
used[i] = true; // "consume" this position
}
}
// Second pass: mark present letters (yellow)
// Only if they haven't been consumed already
for (let i = 0; i < guess.length; i++) {
if (results[i].state === 'correct') continue;
for (let j = 0; j < word.length; j++) {
if (!used[j] && guess[i] === word[j]) {
results[i] = { letter: guess[i], state: 'present' };
used[j] = true;
break;
}
}
}The first pass finds exact position matches and “consumes” them. The second pass then looks for letters that exist in the word but are in the wrong spot — but only against unconsumed positions. This prevents a single letter in the target from lighting up multiple tiles in your guess. It’s a small detail, but it’s the difference between a correct game and a broken one.
Porting It to the Web
Once the Python version was working, I wanted to bring it to the browser — not just as a static demo, but as something you could actually play. I ported the engine to TypeScript, keeping the same two-pass algorithm as the original. The game logic lives in a standalone engine.ts module with no React dependencies, which means it’s testable and portable.
The UI is React with Framer Motion for the tile-flip animations. Each row of tiles reveals left to right with a staggered delay — the same satisfying cadence you get in the real Wordle. The on-screen keyboard tracks letter states across all your guesses, so you can see at a glance which letters you’ve eliminated.
The Word List Problem
Wordle’s word list is a bigger design decision than most people realize. The original game used a curated list of ~2,300 common five-letter words as possible answers, with a much larger set (~10,000) of valid guesses. This distinction matters — you want the answer to always be a word people would reasonably know, but you want obscure words like XYLYL to be valid guesses so players can use elimination strategies.
I pulled my word list from the Scrabble dictionary, filtered to five-letter words, and split it into answer words (common, recognizable) and valid guesses (the full set). It’s the kind of decision that doesn’t look like much in the code — just two arrays — but it has a huge impact on whether the game feels fair.
Why This Project
Portfolio projects have a reputation for being soulless. Another to-do app. Another weather dashboard. I wanted to build something that I would actually use, something with a story behind it. This Wordle clone isn’t going to change the world, but it’s a complete, working piece of software that went from an idea to a Python prototype to a polished web app — and you can play it right here on this page.
It touches real problems: input validation, state management, keyboard event handling, animations, accessible UI, and the surprisingly finicky logic of letter-matching in a word game. It’s small enough to understand in an afternoon and complete enough to demonstrate how I think about building software.
If you played the game above (or are about to), I hope it felt like the real thing. And if you’re curious about the full implementation, the source code is on GitHub — both the original Python CLI and the TypeScript web version powering this page.
Ivan Pedroza
Software Engineer — Seattle, WA