[RFC] SPA Mode Enhancements

[tannerlinsley]

TanStack Start is a unique opportunity for SPAs to have server-side features, but may come with some decisions to make.

What does SPA mode mean?

From my perspective, SPA mode is a general term for NOT server-side rendering a page, which leaves only one way to get the html...

Static Files

Generating static files is the only way to get the html for an "SPA" in the traditional sense of the term. So which files are necessary?

• A catch-all html file that can be used to render any route.
• Optionally, structured html files for each route that can be prerendered.

This brings me to my first question: What is an index.html file?

• An empty shell that acts as a catch-all route?
• An actual rendering of the index page of the app?

Fallback !== Index

Traditionally, we see this recommendation in a _redirects file:

/*    /index.html   200

This tells the server that for any paths that don't exist statically, to redirect to the index.html file.

Non-prerendered index.html

The above configuration works great for a non-prerendered index.html file. The expectation here is that your index.html file now a "shell" of the app with no meaningful content other than the necessary assets to client-render the app into an empty slot.

Prerendered index.html

With prerendering, however, we likely have a different expectation that the index.html file is a fully rendered page representing the index page of the app. Now consider the following scenario:

• User navigates to /non-prerendered-route
• The server redirects to /index.html
• The user is momentarily served the fully rendered homepage
• The app is rendered (or hydrated with hydration errors)
• The user now sees the fully client-rendered /non-prerendered-route content

The above flow produces a flash of content that is far from ideal. So what can be done?

"Shell" vs "Index"

Instead of using the index.html file as a "shell" AND a "prerendered" page, we can instead have two separate files:

• _shell.html - a true shell of the app that can be used to render any route
• *.html - Prerendered pages that can be used to render specific routes, including the index.html file

This way, we can have the best of both worlds. Any prerendered pages can be served as static files, and the _shell.html file can be used as a proper fallback for any routes that don't have a prerendered page.

Implementation

If we now need to generate a "shell" with no meaningful content as a fallback, we need to go a level higher in the rendering process. If we break down our existing layout strategies, we find that there is already a great place to do this: The __root.tsx file. The root component represents the root of the app and is always rendered regardless of the page/route.

In our __root.tsx file, we effectively start rendering page-specific content where the first <Outlet /> is rendered. By "removing" the <Outlet /> from the __root.tsx file, we can effectively render a "shell" of the app that can be used as a fallback for any routes that don't have a prerendered page.

How do we "remove" the <Outlet />?

Let's first assume that we know when the router is currently rendering the "shell" of the app via a new router.isShell flag. Obviously this isn't a real path or route, so we will likely use the index (/) pathname as a runtime placeholder just in case anything in the shell rendering logic attempts to read from the current location.

While we could push the responsibility of "removing" the <Outlet /> to the user, I think it makes more sense to have this behavior require zero changes to the user's code. My best idea so far is to update the <Outlet /> component logic to something like this:

// This is pseudo-code, but I think it gets the point across
const Outlet = () => {
  const router = useRouter()

  if (router.isShell) {
    throw new Error('') // See below
  }

  // ... continue with the existing logic
}

React's secret "client-only mode

https://react.dev/reference/react/Suspense#providing-a-fallback-for-server-errors-and-client-only-content

In React, if we throw an error during SSR that's inside of a suspense boundary:

• The boundary fallback is rendered
• SSR'd HTML is sent to the client with the fallback
• The Suspense boundary is "retried" on the client
• If the client succeeds where the server failed, it continues hydration from that point down, just like a createRoot().render(), but only for that tree.

We can use this approach to solve 2 problems:

• Allowing users to show a fallback for main content. Simply add a pendingComponent to your root route!
• Allowing users to partially SSR some of a routes nested matches. If a route has ssr: false on it, we can error it on the server, then pick up on the client and rerender from there
• Allow users to show fallbacks for the above

Rendering the Shell

Now that we have a means to "remove" the <Outlet /> from the __root.tsx file, we need to render the "shell" of the app. This will mostly likely involve checking the app's configuration to see if "SPA Mode" is enabled, and if so, rendering the "shell" of the app.

As of right now, we would need to either extend Vinxi with additional logic to do a special prerender OR do the migration off of Vinxi to Nitro so we have more control.

However, I have always been a fan of calling things what they are and I think this is a case that could benefit by removing the "SPA Mode" terminology. Instead, I think it makes more sense to call this functionality by its outcome, shell: true or even `shell: '_shell.html' if you want to specify a custom file name.

This way when we configure our app in app.config.tsx we not only have a clear way of enabling an "SPA Mode" but we also have a clear way of configuring the output of the "shell" of the app:

export default defineConfig({
  // ...
  shell: true, // defaults to _shell.html
  // or
  shell: '_my-shell.html',
})

The outcome is predictable from the name alone. This setting, when enabled, will only render the "shell" of our app to the _shell.html file in our public output directory.

Note

Why not just create a route for the shell and not render anything in it?

There are a number of reasons why I dont' think this is a good idea:

• This would place an unnecessary route and route match in the router, potentially pushing users to create links to this route.
• It technically requires more effort from the user to set up.
• It removes our opportunity to do other optimizations, like setting up additional meta tags, etc.

Shells and Robots

It's possible that with a _shell.html file now output in our public directory, that a robot may stumble upon it and index it. This could be problematic for SEO, so there are a few things we can do to mitigate this:

• When rendering the shell, add a <meta name="robots" content="noindex, nofollow"> tag.
• Advise the user to add their shell file to their robots.txt file as an exclusion.

hydrateRoot vs createRoot

Something we need to consider is the difference between hydrateRoot and createRoot from React. Typically we only want to createRoot() and render() when there is no content to hydrate at all. After consulting with Josh Story from the React team, I've learned that calling hydrateRoot, even in circumstances where only a partial match is being hydrated will still result in the most performant outcome.

Sticking with this recommendation, our client.tsx entry files can avoid breaking changes to existing code.

SPA Mode = No SSR + Server Functions + API Routes

All of the above makes the assumption that there is no ssr at all, but that shouldn't mean "no server" completely. The whole idea of an SPA mode is made most valuable when you also have the ability to:

• Use server functions
• Use api routes
• Set up custom websockets, etc.

To do this, we effectively need a way to disable the SSR "router" or handler from handling routes at all. We'll need to figure this out. See below for more info

Hybrid approach?

Does it make sense at all to somehow be able to have an SSR server as well? Anything SSR related could be optional and in addition to the above except for the fallback redirect.

As soon as you have any SSR handler, your http stack needs to go from something like this:

• Static files
• HTML Fallback

to

• Static files
• Server handler (api routes, server functions)
• SSR handler (fallback)

To give the SSR handler a chance, we can no longer use our fallback redirect to _shell and instead fall back to SSR being a requirement.

Some SSR or none at all

To me it seems like you need to make the choice up front whether you are going to do some SSR or none at all, which directly affects the decision up front to either:

• Produce a _shell and rely on HTML fallbacks
• Ship an SSR app (prerendering still available), and add a way for some routes to opt-out of SSR (see below)

SSR + SPA Pages

If the user does want to do some SSR, and the SSR handler exists, that doesn't mean every page should have to be server side rendered. Technically, only the shell would need to be server rendered to achieve the same experience as a _shell + fallback approach.

To do this, we would like need to update our existing SSR handler to detect routes with ssr: false. But a few questions:

• Can the root disable SSR? What would that mean?
• Can we do partial server-rendering? Does disabling SSR for a route simply mean that it's <Outlet /> renders null on the server?

[tannerlinsley]

Alright, so it seems this the right direction to go. We need to start outlining some things to actually build:

• A way using Vinxi to export the static shell file, even if the user hasn't enabled prerendering/SSG
• Upgrade ssr: false to defer all loading to the client, not just the rendering. Currently loaders run for ssr: false routes during SSR and that can produce errors.
• Support ssr: false on the root route. What does this mean? Currently ssr: false for all other routes means "don't run ssr for this route and any children". But for the root route, we need it to run so we can generate the shell and by definition, "ssr" needs to always be enabled for the root route since it will render that shell. To this end, I think ssr: false for the root route is equivalent of setting ssr: false for all child routes.
• Should we make that an official option to disable ssr for all child routes? Something like ssrChildren: false?

[mattkallo]

This feature would really help us migrate our SPA to TanStack. Is this feature currently being developed? Thanks.

[ptmkenny]

I'd like to describe a related use case, that of Ionic mobile apps running on Capacitor.

The Ionic framework provides components for building mobile apps using Angular, React, and Vue. Ionic apps generally run on top of Capacitor, which provides integration with iOS and Android. Ionic components include things like form widgets, tabs, and a mobile router.

Ionic's mobile router component wraps the framework's router. For example, Ionic Angular uses the Angular router, while Ionic Vue uses the Vue router. React, however, doesn't have an "official" router (the Facebook team that releases React does not maintain a router). So, Ionic React is currently using react-router v5. The feature request to add React Router v6/v7 support is the most upvoted request in the ionic-framework issue queue.

Over the past few years, there have been various attempts to update Ionic's React router (built on top of React Router v5) to use v6, but these attempts have failed partly because of react-router's increasing focus on moving everything to SSR.

It seems that Tanstack Router is still providing a non-SSR option, and if I understand correctly, this RFC is attempting to make client-side non-SSR routing even better. So, in addition to the SPA use case, I would like to briefly outline the mobile app use case. If Tanstack Router has first-class support for client-side routing without any SSR, perhaps Ionic React could migrate to using it instead of react-router.

Some background: Capacitor-based mobile apps (and Cordova-based mobile apps) basically package a website that is loaded in a webview on the mobile OS that (unlike a PWA) has access to device features like file storage, push notifications, and in-app purchases. Such apps need a router, but they can't use SSR at all (because the app files are bundled in the app installer distributed through the mobile app store).

Also, mobile routing has some important differences from regular SPA routing.

This comment from one of the Ionic developers explains it well:

So one of the big differences between web apps and mobile apps is with state management. In a mobile app, previous views are typically persisted so users can go back to them. For example, imagine you had a long form on PageA. You entered your email and other information, changed the scroll position, and then pressed a button to go to PageB. Many users expect that when they return to PageA that the page will be exactly how they left it. This means that the scroll position should be preserved, the text they entered into the form should be preserved, etc.
...
The other reason is for swipe to go back on iOS. While on PageB, users should be able to partially swipe back to reveal the contents of PageA. The swipe could happen at any time, so PageA needs to be ready to be shown at any time.

So I'd like to propose this "router run completely client-side in a mobile app" as another use case that could (hopefully, possibly?) be served by an "SPA mode."

[jprosevear]

TanStack Start is a unique opportunity for SPAs to have server-side features, but may come with some decisions to make.

What does SPA mode mean?

From my perspective, SPA mode is a general term for NOT server-side rendering a page, which leaves only one way to get the html...

Static Files

Generating static files is the only way to get the html for an "SPA" in the traditional sense of the term. So which files are necessary?

• A catch-all html file that can be used to render any route.
• Optionally, structured html files for each route that can be prerendered.

This brings me to my first question: What is an index.html file?

• An empty shell that acts as a catch-all route?
• An actual rendering of the index page of the app?

Fallback !== Index

Traditionally, we see this recommendation in a _redirects file:

/*    /index.html   200

This tells the server that for any paths that don't exist statically, to redirect to the index.html file.

Or an nginx rule.

Reading through the rest, I'm trying to understand if this breaks a traditional SPA - ie getting an index page from Django, Rails, nginx, etc. See the implied SPA definition at https://tanstack.com/router/latest/docs/framework/react/guide/document-head-management#single-page-applications

Side note: does not replace the title in for instance of the static page delivered this way already (and presumably the shell concept would need to handle this)..

[garronej]

Upgrade ssr: false to defer all loading to the client, not just the rendering. Currently loaders run for ssr: false routes during SSR and that can produce errors.

Yes please this!!! This is exactly what we need.

[mattymattdev]

Having a clean, typesafe, well-documented API to allow developers to cook up SSR marketing pages and SPA dashboard pages would be very nice and unique to TanStack.

[flodaniel]

If the user does want to do some SSR, and the SSR handler exists, that doesn't mean every page should have to be server side rendered. Technically, only the shell would need to be server rendered to achieve the same experience as a _shell + fallback approach.

We would love to enable SPA mode partially.
Our use case is as follows:

• We have our traditional SPA app already that we want to keep in SPA Mode
• On top of that we have different landing pages as entry points to the SPA app which should be able to use SSR to provide amazing performance, SEO and lighthouse scoring.

[fuadsaud]

One adjacent use case would be to have an app capable of offline usage (entire bundle cached on the client, full client-side navigation) but the ability to still have server-side rendering for the first load or for specific routes that benefit from SEO.

[rvcas]

@mattymattdev @flodaniel I also have this exact use case in mind. I'm most interested in having a few things like landing, about, etc. be ssr and then all the app stuff can be SPA only no server functions just talking to my go API.

I know I could just do

thing.com -> astro
app.thing.com -> tanstack router

but it would be nice to keep it all together. Having a separate deployment for a few marketing pages seems kinda meh. but maybe I'm wrong and I should just embrace the subdomain :D

[garronej]

You don’t strictly need this tech to achieve what you want, it can be handled at the production level. For instance, you could set up an Nginx reverse proxy that routes to different pods based on the URL path. But yeah, I get what you mean.

Edit: Looking at your profile, you most certainly already know that.

[rvcas]

Haha 😅❤️

Yes I am aware that you can set this up with custom routing logic a layer above the application but at the moment I'm seeking something that keeps my deployments a bit more simple than that. Mostly just as a matter of taste. Which is why I was kind of asking if my tastes are silly atm. I've been using sst for deployments because I work on tons of stuff concurrently so I try to keep things as low config as possible.

[christiandesantis]

I ran into this same issue, since I migrated my code back to Tanstack Start because React Router 7.5.3 file based routing doesn't have good support for having nested routes inside directories. Once this migration was done I noticed there wasn't any SSR mode configuration option out of the box (specially for file based routing) as I expected, so after doing my research I found this SSR setup in the Tanstack Router's docs https://tanstack.com/router/latest/docs/framework/react/examples/basic-ssr-file-based which I implemented and adapted to my Tanstack Start file based routing setup. But this solution wasn’t enough because the same way as most of you I didn’t want to necessarily enable SSR for all routes specially for the authenticated ones like dashboards, so at this point I made a hybrid implementation between this SSR setup and the default SPA setup Tanstack Start comes with by default, and succeeded on this. This hybrid implementation allows to choose the default render mode from a config file, and optionally pass an array to either ssr or spa properties of this same config object with regex strings that when matches with the route path it would enforce that specific render mode instead of the default one.
Now, I’m still heavily refactoring this code because it is scattered around multiple files in the project, so I’m still attempting to centralize all this logic to a single module that at the end could be easily imported and executed from the router file or main file, this way I could share with you the complete solution with an npm package you can install and try out. The reason I’m telling you all this is so I can get some feedback about wether I’m going in the right direction or not, so any comments will be appreciated 🙏🏻

[andyblak3]

I'm migrating from react router v7 to tanstack start and I hate that there's no option to fully disable SSR.

In react router I had this.

My app will be full CSR SPA react, so my files need to be served static.

I'm beginner, so finding this thread took a long time. I think it would be great to at least mention this clearly in the docs (that there's no way to disable SSR currently), so people like me don't have to search through the docs for too long.

[ahrorbeksoft]

I'm migrating from react router v7 to tanstack start and I hate that there's no option to fully disable SSR.

In react router I had this.

My app will be full CSR SPA react, so my files need to be served static.

I'm beginner, so finding this thread took a long time. I think it would be great to at least mention this clearly in the docs (that there's no way to disable SSR currently), so people like me don't have to search through the docs for too long.

why not just migrate to tanstack router instead?

[andyblak3]

I'm new to this, so I have no clue xD

But don’t I still need a web server to serve my content? With React Router I don’t care about what happens under the hood, I just run pnpm start and it works.

[ahrorbeksoft]

@andyblak3 there is vite for that, just see tanstack router, i think it is an upgrade for your case. It is ideal for spa apps.

[Albert-Gao]

Most of the SaaS apps I worked with has this pattern,
a before-auth part that needs SSG and after-auth part that needs SPA, I am currently doing this on 2 different domain with next.js for SSG and a SPA setup for app.domain.com. if we can have it built in in tanstack router, would be heaven.

[garronej]

yes!

[akodkod]

I'm using TanStack Start to deploy my app to the web and mobile (using Capacitor and SPA mode). I ran into a problem where I can't specify an absolute URL for server functions in my Capacitor SPA.

I've used this hack to prefix fetch requests with a specific domain, but it would be really cool to have a parameter in the config to do it.

if (globalThis.window !== undefined) {
  const serverOrigin = import.meta.env.VITE_SERVER_ORIGIN?.trim()

  if (serverOrigin) {
    const nativeFetch = globalThis.fetch.bind(globalThis)

    globalThis.fetch = (input: RequestInfo | URL, init?: RequestInit) => {
      try {
        const urlString = typeof input === "string" ? input : String((input as URL | Request).toString?.() ?? input)

        // If already absolute (http/https), leave it as is
        if (/^https?:\/\//i.test(urlString)) {
          return nativeFetch(input as any, init)
        }

        // Otherwise, prefix with server origin, preserving leading slash
        const prefixed = `${serverOrigin.replace(/\/$/, "")}${urlString.startsWith("/") ? "" : "/"}${urlString}`
        return nativeFetch(prefixed, init)
      } catch {
        return nativeFetch(input as any, init)
      }
    }
  }
}

[schiller-manuel]

can you please create a new github issue with some more context?

[boyhax]

im trying to make mobile app using capacitor by making spa build with ability to use server functions but errors showing
""error during build:
SyntaxError: Unexpected token: keyword (default)""
so how you do it . my expectation is to build seperate files one for static and one for server and deploy server to workers or vercel and proxy server url using vite if possible .can we do that ?

[ptmkenny]

@boyhax This issue is an RFC for future improvements to SPA mode, not for requesting help with specific issues you are currently encountering (for that, make a new issue). That said, capacitor mobile apps run on the device, so you can't use SSR/server functions; the code is running on the device, so there is no way for the server to render it.