Why I moved from Astro to TanStack Start
I moved my portfolio to the React stack I use for client work. Getting Astro's loading behavior and performance back took more work.

Astro was doing a good job of running this site. I moved it to TanStack Start anyway, because I wanted the same React setup I use for client work.
The pages looked much the same after the move. Underneath, I had to rebuild things I’d come to take for granted, including when a video player loads and what stays open after you press Back. Performance needed another round of work after launch.
I wanted one React application
React frontend development is the primary service I offer. I already use TanStack Router and Start on client projects, and Cloudflare is where I deploy. Start fit that combination.
Next.js was an option, but Cloudflare support was the sticking point. OpenNext adapts Next’s build output to Workers. Cloudflare’s vinext reimplements its APIs on Vite and reached 1.0 in September. Both left me with compatibility questions I didn’t want to take on for this site.
Next.js has made progress here. Its Deployment Adapter API became stable in 16.2, giving hosting providers a supported way to integrate with its build output. But as of this rewrite, Cloudflare’s verified adapter is still in development. I preferred the Start setup I already knew.
This site gives me somewhere to try things I might later use in client work.
Next, I want to experiment with marketing pages tied to ad campaigns and programmatic SEO. A client area for managing work and billing is another possibility. Keeping those experiments alongside the public site, in one React application, appealed to me.
Astro could have handled those features too. It already supported React, and its prerendered pages and islands suited a site made mostly of writing and portfolio pages. But the implementations I was considering felt patchy compared with working in React throughout.
I chose the development model I wanted to work in. This is a small site, so I have room to experiment and change my mind. The migration still had to preserve what readers already used.
I worked through it with Codex. We kept Git-backed MDX as the CMS and moved the public site first, preserving its URLs, design, and interactions. The marketing experiments and client area could wait.
The awkward pages made the best prototype
The old site mixed Astro pages, Preact components, and Hono endpoints. A homepage prototype would have tested very little of it.
Instead, we started with an interactive Post and the My Next Filing case study. Between them, they exercised diagrams, charts, responsive images, dialogs, video, captions, and MDX imports. We added a database operation and form failure cases, then ran the prototype through Cloudflare Workers.
It broke in useful ways:
- An image imported only by server code ended up in the server build, but its public URL returned a 404.
- Diagrams made an unexpected Google Fonts request.
- Starting development with a cold cache exposed a duplicate React runtime that warm-cache checks had missed.
That gave us a tested combination of Start, Router, React, Vite, and Cloudflare versions to keep together. Fuma Content handled collections and MDX compilation, with vite-imagetools for responsive images.
If you’re trying a similar move, prototype the page with the most things that can break. A few paragraphs and a hero image won’t tell you much about migrating an interactive tutorial.
Astro’s loading directives became my code
Most public pages stayed prerendered. Contact and the Newsletter result page used request-time rendering so their initial HTML could reflect a cookie or an allowed result message. I chose ordinary React hydration with targeted lazy loading and accepted the extra JavaScript.
Prerendering kept the HTML ready. It didn’t preserve the way Astro delayed interactive components.
Take the video player. In Astro, a visibility directive delayed mounting the component, which loaded the enhanced player when it mounted. Copying that component into React would load the player earlier. It could look identical and still make the page heavier.
The React version had to wait for visibility itself. It also had to leave native MP4 playback alone if someone had already pressed Play, keep that fallback working if enhancement failed, and clean up when the reader left.
Search and other heavy interactions needed similar care. Diagrams could stay as build-time work. Replacing an island meant preserving its loading behavior as well as its markup.
I took over more of the content pipeline
Fuma Content compiled the MDX, but publication rules were still the application’s job. Filtering a draft out of a listing didn’t keep its text or images out of the build. Drafts had to be excluded before imports and compilation, with checks against the emitted files.
The conversion also had to leave fenced code examples alone. An old Astro tutorial still needs to show Astro syntax, even when React renders the page around it.
Some of this work gave me a chance to fix things I’d wanted to change. The old build could ask AI to update descriptions, recommendations, and internal links while preparing a release. I want to read those changes before they go live.
Editorial preparation now writes inputs I can review and commit. Builds consume them without asking a model to reinterpret the content.
Local authoring took work too. During the migration, repeated in-process Vite restarts exhausted the heap. The setup has changed since then. Content edits now regenerate the affected inputs and reload the page, while changes to the published set, editorial inputs, or videos restart dev. That’s another piece of tooling I now maintain.
An image change shouldn’t rebuild every format
Images made the build expensive. Recorded cold production builds took roughly eleven and a half minutes, while a warm build took about 41 seconds. Generating image renditions accounted for most of the difference.
The image tooling already hashed source bytes and transformation settings. Our outer cache key threw everything away whenever the lockfile or media-build source changed. An unrelated edit could force thousands of images to regenerate.
We removed that broad invalidation and included encoder settings and image-tool versions in the relevant rendition’s identity. Changing AVIF settings could then leave cached WebP files alone. Renaming an unchanged image could reuse its bytes too.
We also lowered AVIF encoder effort from 6 to 4, keeping the quality setting unchanged. That trades encoding effort for build time, though the same quality setting doesn’t promise identical pixels.
After both changes, a measured cold local build took 5 minutes 25 seconds. A warm build took 41.75 seconds and reused all 3,945 cached renditions without rewriting them.
Those timings came from the changed setup, so they don’t isolate the effect of either fix.
Forms and navigation needed more than a visual check
The old Inquiry handler could save someone’s message and then tell them it had failed. It wrote to the database before sending a notification email. If the email failed, the whole request returned an error. Retrying could save the message again.
Moving the API from Hono to Start gave us a chance to fix that. A saved Inquiry counts as accepted. Notification failures are reported separately, while a failed database insert still returns an error. The change removes a misleading failure message, though it doesn’t guarantee email delivery.
There’s a harder case when the server saves a submission but the browser never receives a readable response. The browser can’t know whether it succeeded. The form keeps the entered values, explains the uncertainty, and leaves the reader to decide whether to retry.
Subscriber links needed similar attention. Replaying a confirmation shouldn’t send another welcome email. An unsubscribe link from an earlier subscription period shouldn’t cancel a renewed one. Conditional writes against the current status and token protect those transitions.
The old handlers understood the same database columns but different transition rules, so keeping an old build didn’t make rollback safe by itself.
Navigation exposed another kind of failure. Open the About portrait, go Back, then return to About, and the dialog could reopen without a click. A content image dialog could return empty and steal focus from the page heading.
The shared fix made viewers release their own overlay when they left, without closing Search or a menu opened in the meantime.
These are useful checks to borrow for a migration:
- Submit a form, then lose the response or leave before it arrives.
- Follow the same confirmation link twice.
- Open a dialog, go Back, and return to the page.
- Keep an old tab open through deployment, then use search and navigation.
Live checks still mattered. Video range requests returned the whole file with HTTP 200 instead of the requested bytes with 206. A Worker fix made seeking and client transfers work as intended, though it still reads past preceding bytes internally. Real-iPhone review remained deferred, and the deployment checks didn’t send live email.
Performance recovered after launch
The home page’s mobile Performance score reached 100 on October 30. I got its performance back and kept the React application I wanted. Getting there took a separate round of work after the migration.
Before launch, four page metrics missed their targets across 45 local Lighthouse runs. Headings and fonts shifted on two pages, while hero images took too long to appear on two Posts. I chose to ship with those problems and fix them afterward.
The home page’s mobile Performance score improved over the follow-up:
- A few days after launch, it scored 73, with Largest Contentful Paint (LCP) at 5.2 seconds.
- On October 24, it reached 97.
- The October 30 mobile report scored 100 for Performance, Accessibility, Best Practices, and SEO, with FCP and LCP at 0.9 seconds, zero blocking time, and Cumulative Layout Shift (CLS) of 0.002.
Astro had scored 99 after the January bundle cleanup. These are single lab runs, made months apart with different Lighthouse versions. They aren’t a controlled comparison of the frameworks.
The heavier pages needed their own checks. By October 30, both layout-shift results and the Avatar Post’s LCP met their targets. The Exam Post was still 0.1 seconds over.
The launch column below contains five-run medians from a local build. The October 30 column contains single PageSpeed Insights mobile runs against the live site, using Lighthouse 13.6.0, an emulated Moto G Power, and simulated Slow 4G. They describe different test setups. CLS measures unexpected movement, while LCP measures when the largest visible content element appears.
All four reported zero blocking time in those runs. They’re lab results, and don’t establish real-user Core Web Vitals. The remaining Exam Post result is also a good reason to keep checking beyond the home page.
I’ve covered the font, asset loading, CSS, and application startup changes in Optimizing the sh*t out of TanStack Start.
Updated November 11, 2026. The next round replaced Tailwind with component-owned CSS, cutting combined HTML, linked CSS and initial JavaScript across all 76 prerendered pages. The October screenshots and table above remain the measurements from this framework migration.
The next feature has to earn the migration
I have the React application I wanted to maintain, with the public site running on it. Some of the migration work improved things immediately. Some of it was work I could have avoided by staying with Astro.
The marketing experiments and client workflows still need to be built. The next feature has to justify the move.