tanstack-start

This skill builds on test-proxy-recorder/proxy-setup. Read it first for the proxy CLI, playwright.config.ts, fixtures, and the record/replay lifecycle before applying TanStack Start patterns.

test-proxy-recorder — TanStack Start SSR

TanStack Start runs loaders and server functions on the server, so their fetch calls go through the proxy without a browser context — the same situation as Next.js SSR. The proxy correlates those requests to the right test session via the x-test-rcrd-id header. Playwright's playwrightProxy.before() already sets it on the browser navigation that triggers SSR, so the id arrives on the incoming server request — the one thing left is to attach it to outgoing server-side requests. Browser-only tests need none of this; the proxy falls back to the globally set session.

All helpers from test-proxy-recorder/tanstack-start are no-ops on the client and no-ops in production unless TEST_PROXY_RECORDER_ENABLED=true is set.

Record against a production build. Use vite build + node .output/server/index.mjs (i.e. pnpm start), not vite dev. The dev server's per-request context differs from the production runtime registerProxyFetch() patches. Because the production server runs in production mode, set TEST_PROXY_RECORDER_ENABLED=true on the app process for the e2e run.

Setup

Recommended — registerProxyFetch() in src/router.tsx

One line tags every server-side fetch — route loaders, server functions, server routes, and TanStack Query's queryFn during SSR prefetch. Call it at the top of src/router.tsx: that module runs on the server for every SSR request, and the call is idempotent, a no-op on the client, and a no-op in production unless the recorder is enabled.

// src/router.tsx
import { QueryClient } from '@tanstack/react-query';
import { createRouter } from '@tanstack/react-router';
import { registerProxyFetch } from 'test-proxy-recorder/tanstack-start';

import { routeTree } from './routeTree.gen';

registerProxyFetch(); // no-op on the client / in production unless TEST_PROXY_RECORDER_ENABLED=true

export function getRouter() {
  const queryClient = new QueryClient();
  return createRouter({ routeTree, context: { queryClient } });
}