SPA mode server build contains unnecessary SSR code

[StevenPewsey]

Which project does this relate to?

Start

Describe the bug

When running tanstack start in SPA mode, the server build contains SSR code.

Your Example Website or App

Steps to Reproduce the Bug or Issue

Add

spa: {
  enabled: true,
}

to the tanstackStart vite plugin config

Run npm build

The built .output/server contains code that would be used to server side render the application. However this isn't actually used at runtime.

Expected behavior

The built .output/server only contains the code needed to run server functions/api routes, so it is as slim as possible.

Screenshots or Videos

No response

Platform

• Start Version: 1.131.31
• OS: macOS
• Bundler: vite
• Bundler Version: 7.1.3

Additional context

No response

[f1shy-dev]

can we make this configurable actually? like it would be great if we can support creating a _shell file while still having SSR it's perfect for my use-case of SSR -> SPA via a service worker

[jk-gan]

I'm looking a way to disable the SSR for my SPA, it seems like it is not possible yet?

[aarjithn]

@jk-gan did you try ssr: false at route?

[zyojv]

is there any update on this?

[andrewdoro]

yeah still happens

[mattfysh]

may be related to https://github.com/TanStack/router/issues/5471

this became rather obvious while trying to integrate tanstack db, where i had this top-level code in a separate module:

export const list = createCollection(
  localStorageCollectionOptions({ ...

even after using ssr: false on routes that wanted to work with this collection in the client only, I noticed a lot of bundling logic that would include the collection import for server-side bundles

even when not using it, just the presence of the createCollection would leads to server-side errors, like:

LocalStorageCollectionError: [LocalStorageCollection] No storage available. Please provide a storage option or ensure window.localStorage is available

my gut feeling being that TSR doesn't quite deliver on the promise of selective SSR

[mattkinnersley]

Having this issue too - upgrading from tanstack router to tanstack start SPA mode is proving difficult.

[jamesleeht]

The docs advertise that the SPA mode allows you to deploy on CDN:

Easier to deploy - A CDN that can serve static assets is all you need.

But unfortunately this only works with a project that is started purely with tanstack router and without start due to this issue.

[jacobgad]

Migrated from Router to Start to take advantage of API routes. Loosing the ability to deploy to a CDN however is a deal breaker. @schiller-manuel are you confirm if this is being looked into? No rush just need to know rough timeline in order to make the decision to roll back.

[schiller-manuel]

@jacobgad what exactly prevents you from deploying to a CDN at the moment?

[sebdanielsson]

This prevents me from deploying my site to GitHub Pages.

[schiller-manuel]

@sebdanielsson how so? the HTML and client assets can be deployed to any static host

[jamesleeht]

@sebdanielsson how so? the HTML and client assets can be deployed to any static host

If you try building with SPA mode enabled, the resultant build is not just a bunch of static assets (just like how it is when building with tanstack router)

[schiller-manuel]

@jamesleeht yes because you also will have a server part (e.g. server routes). if you don't use any server side features of start, don't use spa mode or just don't deploy the server output then

[aarjithn]

@jamesleeht yes because you also will have a server part (e.g. server routes). if you don't use any server side features of start, don't use spa mode or just don't deploy the server output then

sorry bit confused, isn't SPA mode specifically when you don't use any server side features of start?

[schiller-manuel]

no. spa mode just means no SSR.

[sjoerdvanBommel]

@schiller-manuel

don't use spa mode or just don't deploy the server output then

What are we supposed to use instead, then? I tried running pnpm run build && rm -rf dist/server && pnpm run preview in the start-basic-static SPA example project but run into this error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/Users/sjoerdvanbommel/workspace/start-basic-static/dist/server/server.js' imported from /Users/sjoerdvanbommel/workspace/start-basic-static/node_modules/.pnpm/@[email protected]_@[email protected][email protected]_rea_98b5a91692485c50e6af9f012efc5f2e/node_modules/@tanstack/start-plugin-core/dist/esm/preview-server-plugin/plugin.js
    at finalizeResolution (node:internal/modules/esm/resolve:275:11)
    at moduleResolve (node:internal/modules/esm/resolve:932:10)
    at defaultResolve (node:internal/modules/esm/resolve:1056:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:654:12)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:603:25)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:586:38)
    at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:242:38)
    at onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:546:36)
    at TracingChannel.tracePromise (node:diagnostics_channel:344:14)
    at ModuleLoader.import (node:internal/modules/esm/loader:545:21)

I also tried using static prerendering (the prerender option), but ran into the same issue. It kept generated a server folder.

People seem to understand the docs as if SPA mode creates a fully static website, which is what I thought as well. Related questions:

• https://github.com/TanStack/router/discussions/4616
• https://github.com/TanStack/router/discussions/3394#discussioncomment-14920603

[schiller-manuel]

@sjoerdvanBommel what are you trying to achieve here exactly?

[sjoerdvanBommel]

I'm trying to load data during build time and deploy only static files that use that data. At a later point, we want to be able to use SSR and other tanstack start features when needed, but for now, we want to go fully static. Is this possible, or should we use tanstack router until we decide to use other start features?

[sjoerdvanBommel]

@schiller-manuel forgot to tag so not sure if you noticed my comment. I've also tried to use static server functions, but still haven't been able to build only a client output folder