📄 SKILL.md

← Vault

name: tanstack-start-window-location-ssr

description: Fix TanStack Start SSR blank page caused by window.location.origin in JSX

category: web-development

TanStack Start: window.location.origin Breaks SSR

Trigger

Any TanStack Start (Lovable-style) app where a component uses window.location.origin directly in JSX render. The server returns an empty/blank page and the client-side hydration fails silently.

Root Cause

TanStack Start performs server-side rendering (SSR). window is undefined in the Node.js server context. When window.location.origin is evaluated during SSR, it throws an error that crashes the render, resulting in an essentially empty HTML body with just a

.

Symptoms:

  • - console.log in browser shows nothing when clicking a button (handler never attached)
  • - Page appears to load but content is missing or wrong
  • - Native
    click handlers don't fire
  • - No visible errors in UI, but component is broken

    • Fix

    Replace all window.location.origin with the hardcoded domain string.

    `typescript

    // BAD — crashes SSR

    const baseUrl = window.location.origin;

    // GOOD — works in both SSR and client

    const baseUrl = "https://documentos.rochasalesseguros.com.br";

    `

    Always use a hardcoded URL constant for production TanStack Start deployments.

    Verification

    1. After fixing, clean rebuild: rm -rf dist node_modules/.vite .vite && npm run build

    2. Check bundle for remaining window.location:

    `python

    content = open('dist/client/assets/index-Bxxxxxxxxx.js','rb').read()

    print('window.location occurrences:', content.count(b'window.location'))

    # Must be 0

    `

    3. Check SSR output: curl -s "http://127.0.0.1:3010/" | grep -c 'script' — should return >0 if JS is embedded

    4. If still empty, restart service: sudo systemctl restart documentos

    Related

  • - TanStack Start uses Vite with SSR. Browser APIs (window, document, navigator) must be guarded or replaced with server-safe equivalents.
  • - The same applies to document.cookie, localStorage, sessionStorage — they are undefined server-side.
  • - Node version: always use Node 20 for Lovable-style builds (nvm use 20)