feat: remove ClientOnly children from server build

[schiller-manuel]

Summary by CodeRabbit

• New Features

  • Added a client-only page reachable from main navigation that shows a loading fallback and renders client-only content after hydration.
  • Added a WindowSize component that displays the current window width and height on the client.

• Tests

  • Added end-to-end tests for navigation, server-rendered fallback, and client hydration of the window-size UI.
  • Added unit/snapshot tests covering server-side handling of client-only JSX patterns.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds server-side detection and transformation for ClientOnly JSX, a new client-only demo route/component with E2E tests, and integrates JSX candidate collection and handling into the server-fn compiler pipeline.

Changes

Cohort / File(s)	Summary
E2E Demo - Client-only route e2e/react-start/basic/src/components/WindowSize.tsx, e2e/react-start/basic/src/routes/client-only.tsx, e2e/react-start/basic/src/routes/__root.tsx, e2e/react-start/basic/src/routeTree.gen.ts, e2e/react-start/basic/tests/client-only.spec.ts	New WindowSize component; adds /client-only file route and nav entry; registers route in generated route tree; E2E tests validate server fallback and client hydration rendering window dimensions.
Compiler — JSX handler packages/start-plugin-core/src/create-server-fn-plugin/handleClientOnlyJSX.ts	New exported function handleClientOnlyJSX that strips children and converts matched ClientOnly JSX elements to self-closing elements for server output (preserves fallback prop when present).
Compiler — core integration packages/start-plugin-core/src/create-server-fn-plugin/compiler.ts, packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts	Introduces ClientOnlyJSX lookup kind, JSX detection utilities, collects JSX candidates during AST traversal (JSXElement visitor), integrates JSX candidate processing into candidate pipeline, and adds server lookup configuration for ClientOnly JSX.
Tests — clientOnlyJSX suite & fixtures packages/start-plugin-core/tests/clientOnlyJSX/clientOnlyJSX.test.ts, packages/start-plugin-core/tests/clientOnlyJSX/test-files/*, packages/start-plugin-core/tests/clientOnlyJSX/snapshots/server/*	New test harness and numerous test files/snapshots covering basic, multiple, nested, aliased, non-TanStack imports, no-fallback, and negative cases to validate server-side JSX transformation behavior.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant S as Source (TSX files)
  participant C as ServerFnCompiler
  participant H as handleClientOnlyJSX
  participant R as Server Renderer
  participant B as Browser (Client)

  Note over S,C: Build / compile time
  S->>C: Parse AST, detect ClientOnly imports and JSX usage
  C->>H: Send matching JSXElement node(s) (server env)
  H-->>C: Return transformed JSX (children removed, self-closing)
  C-->>R: Emit server-safe code / HTML with preserved fallbacks
  Note over R,B: Runtime / hydration
  R->>B: Send server-rendered HTML (fallback placeholders)
  B->>B: Hydration loads client bundles
  B->>B: Client-only components mount and render (e.g., WindowSize)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• performance: compiler #6190: Modifies ServerFnCompiler pipeline and optimizations; touches the same compiler traversal and fast-path logic.
• fix: compiler plugin #6177: Changes lookup kinds and compiler lookup handling, related to adding new LookupKind/JSX processing.
• fix: trace nested server function factory re-export chain #6166: Adds fast-path resolution/refactor in compiler; overlaps with import resolution and candidate detection areas.

Suggested reviewers

• nlynzaad

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.74% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main change: it introduces server-side handling to strip ClientOnly JSX element children during compilation, which is the core feature across all modified files.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch client-only-server

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 169ef84 and c4faeee.

📒 Files selected for processing (1)

• packages/start-plugin-core/src/create-server-fn-plugin/handleClientOnlyJSX.ts

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript strict mode with extensive type safety for all code

Files:

• packages/start-plugin-core/src/create-server-fn-plugin/handleClientOnlyJSX.ts

**/*.{js,ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Implement ESLint rules for router best practices using the ESLint plugin router

Files:

• packages/start-plugin-core/src/create-server-fn-plugin/handleClientOnlyJSX.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Test
• GitHub Check: Preview

🔇 Additional comments (3)

packages/start-plugin-core/src/create-server-fn-plugin/handleClientOnlyJSX.ts (3)

1-2: LGTM! Clean type imports.

The type-only imports follow TypeScript best practices and properly reference the Babel types needed for AST transformation.

---

4-19: LGTM! Excellent documentation.

The JSDoc clearly explains the transformation purpose and provides helpful before/after examples for both fallback scenarios.

---

20-32: LGTM! Clean and correct transformation logic.

The implementation correctly transforms ClientOnly JSX elements by:

1. Removing all children (client-only content)
2. Converting to a self-closing tag

The mutation-based approach is standard for Babel transformations, and the type safety is solid. The unused _opts parameter (indicated by the underscore prefix) is appropriate for API consistency or future extensibility.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit c4faeee

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	13m 20s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	20s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-12-23 07:25:27 UTC

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6193

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@6193

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6193

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6193

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6193

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6193

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6193

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6193

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6193

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6193

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6193

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6193

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6193

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6193

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6193

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6193

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6193

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6193

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6193

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6193

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@6193

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6193

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6193

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6193

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6193

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6193

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6193

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6193

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6193

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6193

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6193

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6193

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6193

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6193

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6193

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6193

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6193

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6193

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6193

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6193

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6193

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6193

commit: c4faeee