I Broke Replit So You Don't Have To: Building StackShelf
Building in Public: The official patch notes, episode 1.
There Are Two Types of Product Updates
The ones you proudly list in changelogs and marketing decks.
The ones you bury deep under “general improvements” because, well, “accidentally deleted the auth flow” feels too raw.
This series is about the second kind.
Because while StackShelf now behaves like a real, grown-up platform, just two weeks ago it was being held together by stubbornness, and the kind of optimism that borders on delusion.
So here it is - the first post: a full rundown of the behind-the-scenes process, bugs, errors, and mysterious side effects that made up the sleep-deprived road to a something that finally works.
Why I Built It
Substack is designed for writing and building an audience, not for selling.
But here’s the honest truth: most Substackers absolutely want to monetize their expertise.
And picking the best way to do it reminds me of picking the least terrible bathroom at a music festival -none inspire confidence, but you have to go:
Gumroad, Amazon, etc. - your products drift through cyberspace, lost among millions, nowhere near your actual readers.
Rely on blog posts - great, until they dissapear in the feed and your readers struggle to find it when they need it
Cross your fingers and hope new readers just stumble across your offer
If you’ve ever lost your own product in your own newsletter, please know you’re in excellent company. And you deserve better.
So I built StackShelf:
For readers: a simple way to discover everything Substackers have to offer
For writers: a shelf-in-bio: one gorgeous link where you can put everything you offer on proud display
Assumptions & Non-Negotiables
Here’s what I assumed going in:
Substackers care about trust
Substackers want to support each other
Substackers need something like StackShelf – this was instantly validated: this post brought in 88 new subscribers and soooooo many DMs!
Non-negotiables (scribbled pre-code)
Design Choices
Creator first: every decision must prioritize their needs
Shelf-in-bio: beautiful bento-style showcase, no compromises
Visual hierarchy: clear information architecture, users are guided naturally
Performance as design: Speed and responsiveness as essential design features
1-click redirects to Gumroad (or wherever the products actually live)
Color palette: no corpo colors, warm gradients to create optimism and energy
Typography: not another generic vibe coding font
Privacy-first analytics (click counting - yes, tracking who clicked - no)
Tools I used
ChatGPT: Thinking buddy, critic, PRDs, value prop canvas, and prompts for Replit
Figma: Sketches and design files for Replit
Replit: Development, deployment and documentation
Build Process: Things I Broke in Spectacular Fashion
There are plenty to choose from, but today, let’s talk about making Google OAuth work in Replit. This one’s got more twists than a season finale of Game of Thrones.
Right before going on holidays, I decided it was the perfect time to ship the MVP.
My plan was to send it out for testing while I’m away, then come back to an inbox overflowing with thoughtful, actionable feedback. The sort of feedback that makes you want to hug strangers.
You can already see where this is going. Let’s never do that again.
Not one tester could log in.
Not. A. Single. One.
I could, of course, but I’ve long suspected Replit finds me easier to humor than others.
Error 1
I didn’t panic at first. It’ll be a quick fix, I thought, just like every other time.
So, there I was: making dinner, packing my suitcase, toggling between folding socks and debugging in Replit.
Replit responded promptly, made a fix, tested it, and declared victory.
The agent was pleased with itself.
My testers, on the other hand, were not.
, who is much kinder than the situation deserved, stayed on the line as we attempted another round of digital whack-a-mole.
Still, nothing. The login remained an exclusive club, of which I was the only member.
It dragged on for hours.
Replit fixed the authentication → broke the redirect.
It fixed the redirect → broke the authentication, and I started rubbing my temples.
Got that back → the login button vanished, no warning, no farewell note
Re-added the button → and with impressive efficiency, everything looped right back to error one.
By this point I was saying things I’d have to apologize for if computers had feelings. It was 2 am and I realized this bug wasn’t going down tonight - so I did.
What Finally Worked
While on holidays, I kept having replit-related dreams and continued digging into the problem.
It turns out, Google OAuth is a common issue on Replit: I discovered entire Reddit threads devoted to solving it.
And I started taking notes. I dug into their complaints, analyzed patterns, and kept refining a prompt that might solve the problem before it started.
And it did.
When authentication finally worked, I could hardly believe it. I just sat there, afraid to touch anything. It was less victory than cautious disbelief, but hey, I’ll take what I can get.
What I Learned Debugging in Replit
Every single bug taught me something, not just about state management, redirect logic, or the unique flavors of API weirdness, but about resilience, boundaries, and the specific psychology required to debug a mess of your own making.
I built a bulletproof anti-looping prompt out of all this - and, miraculously, it works every time.
The Community Behind StackShelf
In product work, you know you’re onto something special when people show up early -and stay. When they stick around after the first test fails or the prototype breaks, they stop being “testers” and start becoming co-creators.
I’ve been lucky to find those people. StackShelf is, to an embarrassing degree, the product of their patience.
- : a quiet force of leadership and encouragement from day one. He’s contributed so much, I drew him his own doodle avatar (scroll up).
- : another engineering leader, landing a hand even though he's busy building his own app for busy parents.
- : the first author and illustrator to join. That trust means everything!
- & : the ethics and privacy conscience of Substack.
- : my go-to for Substack strategies and the only person who can explain algorithms without sighing.
- : the go-to digital product builder who can turn a napkin sketch into a product before I find a pen
- , , – product and design thinkers whose perspectives will help shape the next phase of testing
- : Creator of Writestack and a strong source of inspiration
- and - the kind of people you want by your side while navigating the AI transition, or honestly, just a Tuesday
- – my favorite designer in the world (we go way back). She just joined Substack and her presence is a gift to the platform.
- – who generously agreed to write a post about StackShelf on his excellent blog. That support goes a long way.
- - Our first adventurous spirit, poet and life coach to join the journey.
- : The mastermind behind all things Substack data, making sense of the numbers like no other.
- : A fellow obsessive learner, always curious and diving deep into new knowledge.
- : our very first supporter from the world of politics.
- : A scientist turned developer, there’s really nothing she can’t do
- : a lawyer turned solopreneur with a sharp mind and kind heart.
To each of you: thank you. I assembled the parts, you gave it a heartbeat. To my readers - you can now see their creator shelves on stackshelf.app
Final Patch Notes
StackShelf is live and in testing
You can sign in, even with Google
I still say “just one last fix” and mean it every time
Bonus: My paid subscribers will get access to my bulletproof anti-looping Replit debug prompt tomorrow
⚡️Why It’s Important To Share This Post ⚡️
It’s crucial that we all spread the word, to kick off the network effects.
If you're not familiar with network effects, think of it like this:
Every share brings more eyes
Each new set of eyes = more readers for everyone
Some of these readers are creators themselves = more content
More content = even more eyes and shares
That’s how we’ll build the viral loop together 🤗
My Other Posts On Substack Community Needs
Community Updates
We’re rising again!
Oh my… I’ve been there so many times, myself. I had to laugh, as well… the laughter of one who knows the pain all too well, and is infinitely relieved that I wasn’t the one going through it. It really is awful, isn’t it? But such is the life. Thank you so much for building this. And thank you for sharing about the process.
So funny and painfully relatable. I ran into the exact same issue with my first Replit build, though my app was waaaay simpler than StackShelf. It was a little PDF tracker (kind of like WeTransfer but for documents, so you could see who opened it, when, if they downloaded it etc). And yup… authentication broke everything. Repeatedly :))
Would love if you shared that reusable prompt that saved the day.
Anyway, enough of my rant.
StackShelf looks awesome, can’t wait to finally have something to sell just so I can put it there haha. Cheering you on!