My personal website is really just a playground. A portfolio, a blog, nothing fancy. No pressure, no deadlines, no team. Just something I come back to when I feel like it. It is the kind of project where you want things to feel smooth and effortless.
For a while, Astro delivered that. But over time, a few friction points started creeping in. Nothing dramatic on its own, but enough to make the experience feel a bit off.
The friction points that built up
Untyped routes
One of the most annoying ones was a typo in a route that quietly broke navigation. No error, no warning. Just a broken link I had to track down manually.
I ended up using astro-typed-routes, which helped. But it still felt like a patch rather than a real solution. Something that should probably be built in instead of added on top.
A mental model that never fully clicked
I also never quite got comfortable with the mix of .astro and .tsx files.
Every time I needed interactivity, I had to switch mental gears. It is not a huge deal, but it creates constant low-level friction points that you definitely feel over time.
Random cache weirdness
Then there were the cache issues. Stale content, random "file not found" errors, schema glitches. Most of the time I fixed it by deleting the cache folder. Not blocking, but just enough small annoying stuff to make me hesitate before opening the project.
The trigger: fumadocs at the right time
The actual trigger came from a random discovery. I was reading the docs for nuqs and noticed it was using Fumadocs both for the documentation but also for the blog part.
That caught my attention because fumadocs had just added support for TanStack Start.
TanStack Start was not new to me. I had already been using it in production since we migrated Start UI earlier in 2025, so I already knew how it behaved and where it could shine. That made the idea of migrating my site feel much less risky.
A surprisingly smooth migration
I expected more pain points, but the migration went surprisingly well.
The main reason for that was the full TypeScript integration and true type safety.
At the same time, I was leaning more into AI-assisted development, and something really clicked. When your codebase is strongly typed, AI becomes much more reliable.
Types act like guardrails. Less guessing, fewer hallucinations, better suggestions. It made refactoring faster and more predictable.
The only real hiccup
The only part that took a bit of effort was migrating content schemas.
Astro has its own schema layer on top of Zod, and it does not always match the latest Zod APIs. Moving to native Zod required a few adjustments, especially around schema references and image handling. But that was a hurdle I could easily handle.
What I gained
Once everything was migrated, the day-to-day experience felt noticeably better:
- Everything is TSX so no more context switching
- Routes are typed out of the box so no extra setup, and so are the route loaders
- Dev server feels faster so tighter feedback loop
- No more weird cache issues so things just behave
- Strong typing made LLM modifications more accurate and reliable, ultimately allowing me to be more creative, faster
It is not a massive transformation, but it is a lot of small wins that add up.
Where Astro still shines
Make no mistake, Astro is still really solid, especially when it comes to complex content setups and advanced schema relationships. Proof is, we used it for building the Fork it! Community and BearStudio websites! If your project leans heavily on that, Astro probably still has the edge.
In my case, for a simple blog and portfolio, that extra complexity was not needed.
What does the future hold?
I recently had the opportunity to go to React Paris and attended Tanner Linsley's talk about TanStack Start.
He teased upcoming support for Server Components, and it looks really interesting. Their approach feels different, and the possibilities are pretty exciting. Being able to cache server components with TanStack Query is especially intriguing.
It is probably overkill for my current site, but I am curious to experiment with it when it lands.
Should you migrate?
I would not recommend migrating just for the sake of it.
But if you have run into similar sources of friction like untyped routes, mental overhead, or cache issues, and especially if you are already using React and TanStack Start elsewhere, then it is worth considering.
Otherwise, if Astro works well for you, there is no strong reason to move. It is a great tool. It just was not the right fit for my use case anymore.
Final thoughts
At the end of the day, this was mostly about finding a setup that feels good to work with for me specifically.
Huge shoutout to Tanner and all of the TanStack contributors for building tools that genuinely improve day-to-day DX and pushing the whole ecosystem forward.
Keep shipping 🚀