Partially disable SSR

[flodaniel]

We are looking to migrate a big codebase to tanstack/router and would love to also start using tanstack/start to enable SSR.
Due to the size of the codebase we would like to disable SSR for most of our current code and only use it for anything new we add.

I have tried to find anything about this in the docs and on github, but I could not find a related option to configure a route (and all subroutes) to be excluded from SSR.

Is there an undocumented config option or a good way to achieve this?

[schiller-manuel]

you can set ssr: false for routes you don't want to SSR

[LukasFritzeDev]

This is working for the component rendering itself, but the loader is still executed on the server if using @tanstack/react-start.

Having this Route:

// app/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod";
import { zodValidator } from "@tanstack/zod-adapter";
import { getProfiles } from "../actions/profile.ts";
import { NoProfiles } from "../components/list/noProfiles.tsx";
import { ProfilesList } from "../components/list/profilesList.tsx";

const QueryParams = z.object({
  contextId: z.string(),
});

export const Route = createFileRoute("/")({
  component: Home,
  validateSearch: zodValidator(QueryParams),
  ssr: false,
  loader: async (ctx) => {
    console.log("loader executed");
    const contextId = ctx.location.search.contextId;
    // this must be executed client side
    return getProfiles({ data: contextId });
  },
});

function Home() {
  console.log("component rendered");

  const profiles = Route.useLoaderData();

  const hasProfiles = !!profiles && profiles.length > 0;

  return (
    <>
      <h1>
        A11y Checker
      </h1>
      {hasProfiles ? <ProfilesList profiles={profiles} /> : <NoProfiles />}
    </>
  );
}

the log message

• component rendered is logged only on the client (the browser dev tools)
• loader executed is printed only on the server side, not on the client
  • I’d expect that the loader function is executed only on the client side as well

Having ssr: false removed or set to true, component rendered is logged on both sides.

Is there a built-in option to execute loaders to fix this?

---

Why must the code be executed client side?

The called server function uses a middleware with a client method. Inside the client method, code is executed to retrieve a session token. This is done in an iFrame context via Window Messages and these can only work in the client browser context.

Since the middleware client method is also executed server side during SSR, my attempt is to disable SSR for routes that use such functions. Another option would be to disable SSR completely, but I didn’t find any documentation on how to do this with @tanstack/start either.

[LukasFritzeDev]

My current workaround is to return null in the loader if executed server side and invalidate the router using useEffect:

export const Route = createFileRoute("/")({
  component: Home,
  ssr: false,
  loader: async (ctx) => {
    // check if executed not in browser context
    if (typeof window === "undefined") {
      return null;
    }
    // ...
  },
});

function Home() {
  const profiles = Route.useLoaderData();
  const router = useRouter();

  useEffect(() => {
    router.invalidate({ sync: true });
  }, []);

  // ....

Not that pretty, but functional.

[shinzui]

Hi! We're running into the same issue. We're using Relay with TanStack Router and are looking to migrate to TanStack Start, but we'd like to avoid having to use the workaround on every route. Are there any plans to support disabling SSR without needing that workaround?

[Ashvith10]

@schiller-manuel Ah, that's unfortunate. I wanted to eliminate the need for the server itself, since I am targeting KaiOS. Perhaps Tanstack Start isn't the right tool?

[schiller-manuel]

spa mode then?

[Ashvith10]

@schiller-manuel SPA mode keeps failing for me. I've also tried "nitro": "npm:nitro-nightly@latest", and that also hasn't worked for me.

[prerender] Prerendering pages...

 ╭───────── [Build Info] ───────────╮
 │                                  │
 │  - Build Directory: .output      │
 │  - Date: 11/1/2026, 12:50:15 pm  │
 │  - Nitro Version: 3.0.1-alpha.1  │
 │  - Nitro Preset: node-server     │
 │                                  │
 ╰──────────────────────────────────╯

ℹ Spawning preview server...                                                                                                                               12:50:15 pm
ℹ node ./server/index.mjs                                                                                                                                  12:50:15 pm

[prerender] Concurrency: 8
[prerender] Crawling: /
[prerender] Prerendered 0 pages:
file:///home/ashvith/Desktop/convo-ng/node_modules/@tanstack/start-plugin-core/dist/esm/prerender.js:137
            throw new Error(`Failed to fetch ${page.path}: ${res.statusText}`, {
                  ^

Error: Failed to fetch /: Internal Server Error
    at file:///home/ashvith/Desktop/convo-ng/node_modules/@tanstack/start-plugin-core/dist/esm/prerender.js:137:19
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async file:///home/ashvith/Desktop/convo-ng/node_modules/@tanstack/start-plugin-core/dist/esm/queue.js:38:17 {
  [cause]: Response {
    [Symbol(state)]: {
      aborted: false,
      rangeRequested: false,
      timingAllowPassed: true,
      requestIncludesCredentials: true,
      type: 'default',
      status: 500,
      timingInfo: {
        startTime: 38278.763972,
        redirectStartTime: 0,
        redirectEndTime: 0,
        postRedirectStartTime: 38278.763972,
        finalServiceWorkerStartTime: 0,
        finalNetworkResponseStartTime: 38324.890909,
        finalNetworkRequestStartTime: 38298.756369,
        endTime: 0,
        encodedBodySize: 253,
        decodedBodySize: 0,
        finalConnectionTimingInfo: {
          domainLookupStartTime: 38278.763972,
          domainLookupEndTime: 38278.763972,
          connectionStartTime: 38278.763972,
          connectionEndTime: 38278.763972,
          secureConnectionStartTime: 38278.763972,
          ALPNNegotiatedProtocol: undefined
        }
      },
      cacheState: '',
      statusText: 'Internal Server Error',
      headersList: HeadersList {
        cookies: null,
        [Symbol(headers map)]: Map(8) {
          'vary' => { name: 'vary', value: 'Origin' },
          'content-security-policy' => {
            name: 'content-security-policy',
            value: "default-src 'none'"
          },
          'x-content-type-options' => { name: 'x-content-type-options', value: 'nosniff' },
          'content-type' => { name: 'content-type', value: 'text/html; charset=utf-8' },
          'content-length' => { name: 'content-length', value: '253' },
          'date' => { name: 'date', value: 'Sun, 11 Jan 2026 07:20:15 GMT' },
          'connection' => { name: 'connection', value: 'keep-alive' },
          'keep-alive' => { name: 'keep-alive', value: 'timeout=5' }
        },
        [Symbol(headers map sorted)]: null
      },
      urlList: [ http://localhost:3000/ ],
      body: {
        stream: ReadableStream {
          [Symbol(kType)]: 'ReadableStream',
          [Symbol(kState)]: [Object: null prototype] {
            disturbed: false,
            reader: undefined,
            state: 'readable',
            storedError: undefined,
            transfer: [Object: null prototype],
            controller: [ReadableByteStreamController]
          },
          [Symbol(nodejs.webstream.isClosedPromise)]: {
            promise: [Promise],
            resolve: [Function (anonymous)],
            reject: [Function (anonymous)]
          },
          [Symbol(nodejs.webstream.controllerErrorFunction)]: [Function (anonymous)]
        },
        source: null,
        length: null
      }
    },
    [Symbol(headers)]: Headers {}
  }
}

[schiller-manuel]

full reproducer project please

[Ashvith10]

@schiller-manuel Unfortunately, I've been trying since the last three hours, and I can't get to create a reproducible example in Stackblitz or CodeSandbox. I'll try creating one again, but here's what I've used to generate the project:

npm create @tanstack/start@latest my-app -- --framework solid --deployment nitro --toolchain eslint --tailwind

Perhaps the missing context was that I am using Solid?

[AndyBodnar]

For partially disabling SSR during migration, you can use the ssr option in your route configuration.

In TanStack Start, try this approach:

// routes/legacy-section.tsx
export const Route = createFileRoute("/legacy-section")({ 
  // Disable SSR for this route tree
  ssr: false,
  component: LegacySection,
})

For a whole subtree, you can set this in the parent route and it should cascade down.

Alternatively, use loader with clientOnly patterns:

export const Route = createFileRoute("/legacy")({ 
  loader: async () => {
    if (typeof window === "undefined") {
      // Return minimal data for SSR
      return { data: null }
    }
    // Full data fetch on client
    return { data: await fetchData() }
  }
})

This lets you incrementally adopt SSR for new routes while keeping existing code client-only. The migration can then happen route-by-route.