---
title: "Why I moved from Astro to TanStack Start"
url: "https://sarthakmishra.com/library/blog/astro-to-tanstack-start"
description: "I moved my portfolio to the React stack I use for client work. Getting Astro's loading behavior and performance back took more work."
image: "https://sarthakmishra.com/og-images/blog/astro-to-tanstack-start.webp"
---

[View HTML](https://sarthakmishra.com/library/blog/astro-to-tanstack-start) · [Site index](https://sarthakmishra.com/llms.txt)

# 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.

![Colorful vintage televisions display abstract symbols and retro website layouts.](https://sarthakmishra.com/assets/astro-to-tanstack-start-hero-D8dI-dYi.jpeg)

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](https://opennext.js.org/cloudflare) adapts Next’s build output to Workers. Cloudflare’s [vinext](https://blog.cloudflare.com/vinext-nextjs-on-vite) 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](https://nextjs.org/blog/nextjs-across-platforms), 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](https://nextjs.org/docs/app/getting-started/deploying#verified-adapters). 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.

Why Start fit this site · Cloudflare deployment · TanStack Start · Router and Start in client work · One familiar application · Public portfolio now · Marketing experiments next · Possible client area

This was a choice about my deployment setup and client work. Astro already supported React components.

## 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.

Who delays the enhanced video player? · Yes · No · Load fails · Astro page · Visibility directive · Mount component · Load enhanced player · React page · Mount component · Application waits for visibility · Native playback started? · Keep native playback · Try enhanced player

The visibility delay moved from an Astro directive into application code. Native playback still needed to work without enhancement.

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](https://github.com/fuma-nama/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.

Rebuild only the affected image renditions · AVIF settings change · AVIF cache identity changes · WebP cache identity unchanged · Regenerate AVIF · Reuse cached WebP

With unchanged source bytes and WebP settings, an AVIF settings change no longer discards the cached WebP output.

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.

What the browser knows after a submission · Accepted · Rejected · Lost or unreadable · Submit Inquiry · Browser receives a result? · Show success · Keep values and show error · Keep values and explain uncertainty · Reader decides whether to retry

A missing response cannot tell the browser whether the server saved the Inquiry. An automatic retry could save it twice.

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](https://pagespeed.web.dev/analysis/https-sarthakmishra-com/x5yjk1zd4x?form_factor=mobile) 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](https://sarthakmishra.com/library/blog/optimizing-astro-bundle-size). These are single lab runs, made months apart with different Lighthouse versions. They aren’t a controlled comparison of the frameworks.

![PageSpeed Insights mobile report for the TanStack Start home page: Performance 100, Accessibility 100, Best Practices 100, SEO 100, with First Contentful Paint 0.9 seconds, Largest Contentful Paint 0.9 seconds, Total Blocking Time 0 milliseconds, Cumulative Layout Shift 0.002, and Speed Index 0.9 seconds.](https://sarthakmishra.com/assets/pagespeed-home-mobile-2026-10-30-C9vUehQp.jpeg)

The TanStack Start home page on PageSpeed Insights, mobile run, October 30, 2026.

![Lighthouse mobile report for the Astro home page: Performance 99, Accessibility 96, Best Practices 100, SEO 92, with First Contentful Paint 1.0 second, Largest Contentful Paint 2.0 seconds, Total Blocking Time 0 milliseconds, Cumulative Layout Shift 0.007, and Speed Index 1.0 second.](https://sarthakmishra.com/assets/site-lighthouse-score-12-01-2026-DkLywte2.jpeg)

The Astro home page in January 2026, after its bundle cleanup.

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.

| Page                                                                                                                                         | Metric | At launch | October 30 | Target  |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | ---------- | ------- |
| [Blog listing](https://pagespeed.web.dev/analysis/https-sarthakmishra-com-blog/h3rgljjddf?form_factor=mobile)                                | CLS    | 0.196     | 0.000      | ≤ 0.1   |
| [Newsletter Issue](https://pagespeed.web.dev/analysis/https-sarthakmishra-com-newsletter-issue-1/xhxbmmuy94?form_factor=mobile)              | CLS    | 0.213     | 0.002      | ≤ 0.1   |
| [Exam Post](https://pagespeed.web.dev/analysis/https-sarthakmishra-com-blog-stop-fixing-exams/lxk9cz3pgf?form_factor=mobile)                 | LCP    | 2.931 s   | 2.6 s      | ≤ 2.5 s |
| [Avatar Post](https://pagespeed.web.dev/analysis/https-sarthakmishra-com-blog-building-interactive-svg-avatar/df43sm8y1h?form_factor=mobile) | LCP    | 3.280 s   | 1.8 s      | ≤ 2.5 s |

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](https://sarthakmishra.com/library/blog/optimizing-tanstack-start).

**Updated November 11, 2026.** The next round [replaced Tailwind with component-owned CSS](https://sarthakmishra.com/library/blog/tailwind-to-native-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.**

## Media sources

### Why Start fit this site

```mermaid
flowchart TD
C[Cloudflare deployment] --> S[TanStack Start]
T[Router and Start in client work] --> S
S --> A[One familiar application]
A --> P[Public portfolio now]
A -.-> M[Marketing experiments next]
A -.-> F[Possible client area]
class S blue
class P green
class M orange
class F orange
```

### Who delays the enhanced video player?

```mermaid
flowchart TD
A[Astro page] --> V[Visibility directive]
V --> M[Mount component]
M --> E[Load enhanced player]
R[React page] --> C[Mount component]
C --> W[Application waits for visibility]
W --> P{Native playback started?}
P -->|Yes| N[Keep native playback]
P -->|No| L[Try enhanced player]
L -->|Load fails| N
class V blue
class W blue
class N green
class E violet
class L violet
```

### Rebuild only the affected image renditions

```mermaid
flowchart TD
C[AVIF settings change] --> A[AVIF cache identity changes]
C --> W[WebP cache identity unchanged]
A --> R[Regenerate AVIF]
W --> K[Reuse cached WebP]
class A orange
class R orange
class W green
class K green
```

### What the browser knows after a submission

```mermaid
flowchart TD
S[Submit Inquiry] --> R{Browser receives a result?}
R -->|Accepted| A[Show success]
R -->|Rejected| E[Keep values and show error]
R -->|Lost or unreadable| U[Keep values and explain uncertainty]
U --> D[Reader decides whether to retry]
class A green
class E red
class U yellow
class D blue
```

## Structured data

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "@id": "https://sarthakmishra.com/#website",
      "url": "https://sarthakmishra.com/",
      "name": "Sarthak Mishra",
      "publisher": {
        "@id": "https://sarthakmishra.com/#person"
      },
      "inLanguage": "en"
    },
    {
      "@type": "Person",
      "@id": "https://sarthakmishra.com/#person",
      "name": "Sarthak Mishra",
      "url": "https://sarthakmishra.com/about",
      "jobTitle": "Design Engineer",
      "image": "https://sarthakmishra.com/og-images/sarthak-mishra.webp",
      "sameAs": [
        "https://github.com/SarthakMishra",
        "https://www.linkedin.com/in/itssarthakmishra/",
        "https://x.com/MishraMishry"
      ]
    },
    {
      "@type": "WebPage",
      "@id": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start#webpage",
      "url": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start",
      "name": "Why I moved from Astro to TanStack Start - Sarthak",
      "description": "I moved my portfolio to the React stack I use for client work. Getting Astro's loading behavior and performance back took more work.",
      "inLanguage": "en",
      "isPartOf": {
        "@id": "https://sarthakmishra.com/#website"
      },
      "mainEntity": {
        "@id": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start#content"
      },
      "breadcrumb": {
        "@id": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start#breadcrumb"
      }
    },
    {
      "@id": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start#content",
      "url": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start",
      "name": "Why I moved from Astro to TanStack Start",
      "description": "I moved my portfolio to the React stack I use for client work. Getting Astro's loading behavior and performance back took more work.",
      "mainEntityOfPage": {
        "@id": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start#webpage"
      },
      "author": {
        "@id": "https://sarthakmishra.com/#person"
      },
      "datePublished": "2026-10-20T00:00:00.000Z",
      "dateModified": "2026-11-11T00:00:00.000Z",
      "inLanguage": "en",
      "keywords": [
        "astro",
        "tanstack",
        "react",
        "web-development",
        "performance"
      ],
      "@type": "BlogPosting",
      "headline": "Why I moved from Astro to TanStack Start",
      "publisher": {
        "@id": "https://sarthakmishra.com/#person"
      },
      "image": "https://sarthakmishra.com/og-images/blog/astro-to-tanstack-start.webp"
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://sarthakmishra.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Blog",
          "item": "https://sarthakmishra.com/library/blog"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "Why I moved from Astro to TanStack Start",
          "item": "https://sarthakmishra.com/library/blog/astro-to-tanstack-start"
        }
      ]
    }
  ]
}
```
