[Bug]: Hydration failed error on HMR code update in TanStack Start

[Alan-aj]

Which project does this relate to?

Start

Describe the bug

Hi, in a TanStack Start project, when I am updating code during development triggers a hydration failure. While the change is reflected immediately via Hot Module Replacement, a subsequent manual browser reload results in a "Hydration failed" error. The issue persists until the dev server is stopped and restarted.

Your Example Website or App

https://github.com/Alan-aj/tanstack-start

Steps to Reproduce the Bug or Issue

1. Initialize a project using the TanStack Start Starter Template.
2. Run the development server.
3. Modify a component (e.g., change text) and save.
4. Observe the change reflecting in the browser via HMR.
5. Manually reload the browser page.
6. Check the console for the following error
   Uncaught Error: Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used: ...

Expected behavior

Should reload without errors

Screenshots or Videos

Platform

• Router / Start Version: 1.157.17
• OS: Windows, Linux
• Browser: Chrome
• Browser Version: 144.0.7559.110
• Bundler: Vite
• Bundler Version: 7.3.1

Additional context

[schiller-manuel]

can you please provide the exact project that you generated as a git repo?

[Alan-aj]

can you please provide the exact project that you generated as a git repo?

https://github.com/Alan-aj/tanstack-start

[schiller-manuel]

this is caused by the nitro vite plugin. if it is commented out, the hydration error disappears.
looks like nitro caches something here because the SSR HTML is containg the old values still?

cc @pi0

[pi0]

Nitro doesn't adds any chaching (neither runtime or headers) very strange...

@schiller-manuel Does it happen in minimal tanstack project too?

[chshouyu]

I also frequently encounter this error.

I just create a new project with pnpm create @tanstack/start@latest, add a route file src/routes/about.tsx, then the Chrome console report this error.

Sometimes making modifications in the loader also triggers this error, but sometimes it doesn't, sometimes it does – it's inconsistent.

The vite.config.ts just from the @tanstack/start@latest template

import { defineConfig } from 'vite'
import { devtools } from '@tanstack/devtools-vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'
import viteTsConfigPaths from 'vite-tsconfig-paths'
import { fileURLToPath, URL } from 'url'

import tailwindcss from '@tailwindcss/vite'
import { nitro } from 'nitro/vite'

const config = defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
  plugins: [
    devtools(),
    nitro(),
    // this is the plugin that enables path aliases
    viteTsConfigPaths({
      projects: ['./tsconfig.json'],
    }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
})

export default config

[chshouyu]

After some testing, I found that the Netlify template is relatively stable, while the Cloudflare template and the Nitro template have the same hydration issues.

[tommerty]

Thought I was going crazy until I found this, can confirm the same.

[advany]

+1

[dkjym]

I'm just using nitro for build only

import tailwindcss from "@tailwindcss/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";

import { defineConfig } from "vite";

export default defineConfig(({ command }) => ({
  server: {
    port: 3000,
  },
  plugins: [
    tailwindcss(),
    tanstackStart(),
    viteReact(),
    command === "build" && nitro(),
  ],
}));