chore(examples): Update Clerk server handler usage #5026
main fromrefs/pull/5026/head·merged by schiller-manuel(GitHub profile, opens in a new tab) See
Summary by CodeRabbit#
Chores
- Updated an internal dependency to v0.23.0 in the React Start example.
Refactor
- Moved server handler composition to a per-request (lazy) initialization model for cleaner runtime behavior.
- No user-facing behavior or public API changes expected.
- 1
View your CI Pipeline Execution ↗ for commit 4d189adde3c1fa8687f9513b9d880a76798cb895
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 1m 8s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 4s View ↗
☁️ Nx Cloud last updated this comment at
2025-09-10 16:37:36UTCMore templates
- tanstack-router-solid-example-basic
- 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-streaming-file-based
- tanstack-router-solid-example-kitchen-sink-file-based
- tanstack-router-solid-example-quickstart-file-based
- tanstack-solid-start-example-bare
- tanstack-solid-start-example-basic
- tanstack-solid-start-example-basic-static
- 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-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-start-example-basic-react-query
- tanstack-start-example-basic-rsc
- tanstack-start-example-basic-static
- tanstack-start-example-clerk-basic
- tanstack-start-example-convex-trellaux
- tanstack-start-example-counter
- tanstack-start-example-large
- tanstack-start-example-material-ui
- 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/arktype-adapter
npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5026@tanstack/directive-functions-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5026@tanstack/eslint-plugin-router
npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5026@tanstack/history
npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5026@tanstack/react-router
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5026@tanstack/react-router-devtools
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5026@tanstack/react-router-ssr-query
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5026@tanstack/react-start
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5026@tanstack/react-start-client
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5026@tanstack/react-start-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-plugin@5026@tanstack/react-start-server
npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5026@tanstack/router-cli
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5026@tanstack/router-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5026@tanstack/router-devtools
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5026@tanstack/router-devtools-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5026@tanstack/router-generator
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5026@tanstack/router-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5026@tanstack/router-ssr-query-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5026@tanstack/router-utils
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5026@tanstack/router-vite-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5026@tanstack/server-functions-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5026@tanstack/solid-router
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5026@tanstack/solid-router-devtools
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5026@tanstack/solid-start
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5026@tanstack/solid-start-client
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5026@tanstack/solid-start-plugin
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-plugin@5026@tanstack/solid-start-server
npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5026@tanstack/start-client-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5026@tanstack/start-plugin-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5026@tanstack/start-server-core
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5026@tanstack/start-server-functions-client
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-functions-client@5026@tanstack/start-server-functions-fetcher
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-functions-fetcher@5026@tanstack/start-server-functions-server
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-functions-server@5026@tanstack/start-storage-context
npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5026@tanstack/valibot-adapter
npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5026@tanstack/virtual-file-routes
npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5026@tanstack/zod-adapter
npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5026commit:
4d189adActionable comments posted: 1
🧹 Nitpick comments (1)
examples/react/start-clerk-basic/src/server.ts (1)
9-13: Good refactor to a Clerk-aware handler factory; consider a tiny naming/type hint (optional).handlerFactory is clear enough, but a more explicit name (e.g., createClerkStartHandler) or a type alias can help future maintainers. Optional.
Example lightweight tweak (no behavior change):
-const handlerFactory = createClerkHandler( +// Produces a per-event Start handler wired up with Clerk +const createClerkStartHandler = createClerkHandler( createStartHandler({ createRouter, }), )And update usages accordingly.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📥 Commits
Reviewing files that changed from the base of the PR and between a98c89c5e29efbf649069ecbf0f5ae2c837a337e and cd616c262920caef05b7bff63d69c5745f676c33.
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (2)
examples/react/start-clerk-basic/package.json(1 hunks)examples/react/start-clerk-basic/src/server.ts(1 hunks)
⏰ 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)
examples/react/start-clerk-basic/src/server.ts (3)
4-4: Importing defineHandlerCallback is the right move for platform-friendly exports.This aligns the entrypoint with the latest TanStack Start guidance and avoids subtle platform adapter issues. Looks good.
9-18: No legacyclerkHandlerusage detectedI ran a repository-wide search for any remaining calls to
clerkHandler(and found no matches. All examples now consistently use the newhandlerFactorypattern.
15-18: Build Failure: Example’s Vite Config Missing Plugin The build is failing due to a missing@tanstack/react-startVite plugin in the example’snode_modules, so we can’t verify the inline-nit change until the example successfully builds. Please ensure the example’s dependencies and Vite config are correct, then re-run:pnpm install pnpm -F tanstack-start-example-clerk-basic run buildOnce the build succeeds, you can optionally apply the one-liner inline:
-export default defineHandlerCallback(async (event) => { - const startHandler = await handlerFactory(defaultStreamHandler) - return startHandler(event) -}) +export default defineHandlerCallback(async (event) => (await handlerFactory(defaultStreamHandler))(event))examples/react/start-clerk-basic/package.json line 12@@ -9,4 +9,4 @@99 "start": "vite start"1010 },1111 "dependencies": {12- "@clerk/tanstack-react-start": "^0.19.0",12+ "@clerk/tanstack-react-start": "^0.23.0",💡 Verification agent
🧩 Analysis chain
Version bump aligns with the new server handler pattern; verify peer deps.
The upgrade to @clerk/tanstack-react-start ^0.23.0 matches the server refactor in src/server.ts. Please verify that peer dependency ranges for React, @tanstack/react-start, and router packages are satisfied after the bump, and that the lockfile is updated.
Run from the repo root to surface any peer dep or type issues:
🏁 Script executed:
#!/bin/bash set -euo pipefail # Check for unresolved peer deps and version mismatches pnpm -w install # Inspect the example app deps and hoisting results pnpm -F tanstack-start-example-clerk-basic ls @clerk/tanstack-react-start @tanstack/react-start react react-dom # Typecheck the example to ensure the new handler API is satisfied pnpm -F tanstack-start-example-clerk-basic run buildLength of output: 3933
🏁 Script executed:
#!/bin/bash set -euo pipefail # Print the example's package.json to verify dependencies sed -n '1,200p' examples/react/start-clerk-basic/package.json echo "----" # Print the example's Vite config to inspect imports sed -n '1,200p' examples/react/start-clerk-basic/vite.config.tsLength of output: 1323
#!/bin/bash set -euo pipefail # Search for the Vite plugin entry in the react-start package source echo "Searching for 'plugin/vite' references:" rg -n "plugin/vite" -C2 packages/react-start echo # List files under the plugin directory, if it exists echo "Listing plugin directory contents (if present):" if [ -d "packages/react-start/plugin/vite" ]; then find packages/react-start/plugin/vite -maxdepth 2 -type f -print else echo "packages/react-start/plugin/vite directory not found" fi
#!/usr/bin/env bash set -euo pipefail echo "Listing 'packages/react-start/plugin' directory:" if [ -d "packages/react-start/plugin" ]; then find packages/react-start/plugin -maxdepth 2 -type f -print else echo " packages/react-start/plugin directory not found" fi echo echo "Searching for 'plugin/vite' references in packages/react-start:" rg -n "plugin/vite" -C2 packages/react-start || echo " No 'plugin/vite' references found" echo echo "Searching for 'tanstackStart' export in packages/react-start:" rg -n "export .*tanstackStart" -C3 packages/react-start || echo " No 'tanstackStart' export found"
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "Directory structure under packages/react-start (depth=2):" find packages/react-start -maxdepth 2 -type d echo echo "Contents of plugin/vite directory if it exists:" if [ -d "packages/react-start/plugin/vite" ]; then find packages/react-start/plugin/vite -maxdepth 2 -type f else echo "packages/react-start/plugin/vite not found" fi echo echo "Searching for tanstackStart export in react-start sources:" rg -n "export .*tanstackStart" -C3 packages/react-start || echo "No tanstackStart export found"Length of output: 754
Critical: Example build broken by invalid Vite plugin import
Peer dependencies (React ^19.0.0, @tanstack/react-start ^1.131.28, router packages ^1.131.28) are correctly satisfied and the lockfile is up-to-date, but the example fails to build due to a missing plugin entrypoint.
Please address the following before merging:
- examples/react/start-clerk-basic/vite.config.ts
The line
errors at build time becauseimport { tanstackStart } from '@tanstack/react-start/plugin/vite'@tanstack/react-startdoes not export aplugin/vitepath. - Verify and correct the Vite plugin entrypoint in the
@tanstack/react-startpackage (or adjust the import to the actual plugin location). - After fixing the import, confirm:
pnpm -w installcompletes with no unresolved peerspnpm -F tanstack-start-example-clerk-basic run buildsucceeds without errors
Some conflicts to be resolved
Some conflicts to be resolved
Fixed
Sign in to join this conversation.
Walkthrough#
Bumps
@clerk/tanstack-react-startto ^0.23.0 and refactors the server entry to usedefineHandlerCallback, resolving a per-eventstartHandlervia ahandlerFactoryand delegating each event to the resolved handler.Changes#
examples/react/start-clerk-basic/package.json@clerk/tanstack-react-startfrom^0.19.0to^0.23.0.examples/react/start-clerk-basic/src/server.tsdefineHandlerCallback; createhandlerFactoryviacreateClerkHandler(createStartHandler({ createRouter })); change default export todefineHandlerCallback(async (event) => { const startHandler = await handlerFactory(defaultStreamHandler); return startHandler(event); }).Sequence Diagram(s)#
Estimated code review effort#
🎯 3 (Moderate) | ⏱️ ~20 minutes
Pre-merge checks (2 passed, 1 warning)#
❌ Failed Checks (1 warning)
✅ Passed Checks (2 passed)
Poem#
Tip
👮 Agentic pre-merge checks are now available in preview!
Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
📜 Recent review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between 74b41fdcb0a879896ea50ca2b3c18c9d8f419974 and e81d72d034c273ce2be39ef698768116b039b4fe.
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml📒 Files selected for processing (1)
examples/react/start-clerk-basic/package.json(1 hunks)🚧 Files skipped from review as they are similar to previous changes (1)
⏰ 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)
✨ Finishing Touches
🧪 Generate unit tests
Comment `@coderabbitai help` to get the list of available commands and usage tips.