Skip to content
Source
Sign inSign up
TanStack/router

chore(examples): Update Clerk server handler usage #5026

Mergedwobsoriano(GitHub profile, opens in a new tab)merged 5 commits intomain fromrefs/pull/5026/headmerged 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. Walkthrough

      Bumps @clerk/tanstack-react-start to ^0.23.0 and refactors the server entry to use defineHandlerCallback, resolving a per-event startHandler via a handlerFactory and delegating each event to the resolved handler.

      Changes

      Cohort / File(s)Summary
      Dependency update
      examples/react/start-clerk-basic/package.json
      Update dependency @clerk/tanstack-react-start from ^0.19.0 to ^0.23.0.
      Server handler refactor
      examples/react/start-clerk-basic/src/server.ts
      Import defineHandlerCallback; create handlerFactory via createClerkHandler(createStartHandler({ createRouter })); change default export to defineHandlerCallback(async (event) => { const startHandler = await handlerFactory(defaultStreamHandler); return startHandler(event); }).

      Sequence Diagram(s)

      sequenceDiagram
        autonumber
        actor Client
        participant Server as Server\n(defineHandlerCallback)
        participant Factory as handlerFactory
        participant Clerk as createClerkHandler
        participant Start as createStartHandler
        participant Handler as startHandler
        participant Stream as defaultStreamHandler
      
        Client->>Server: HTTP request (event)
        Note over Server: Wrapped by defineHandlerCallback
        Server->>Factory: await handlerFactory(defaultStreamHandler)
        Factory->>Clerk: createClerkHandler(...)
        Clerk->>Start: createStartHandler({ createRouter })
        Clerk-->>Factory: awaitable handler
        Factory-->>Server: startHandler
        Server->>Handler: startHandler(event)
        Handler->>Stream: Delegate as needed
        Handler-->>Server: Response
        Server-->>Client: Response

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~20 minutes

      Pre-merge checks (2 passed, 1 warning)

      ❌ Failed Checks (1 warning)
      Check NameStatusExplanationResolution
      Description Check⚠️ WarningThe description only provides external links without summarizing the changes, motivations, or testing instructions, leaving reviewers without necessary context to understand and verify the update.Expand the description to include a concise summary of the package bump and handler refactor, the rationale behind the change, any testing steps, and consider adding a PR template to ensure consistent and complete future descriptions.
      ✅ Passed Checks (2 passed)
      Check NameStatusExplanation
      Title Check✅ PassedThe title clearly and concisely describes updating the Clerk server handler usage in the examples without extraneous details, making it specific to the main change in this pull request.
      Docstring Coverage✅ PassedNo functions found in the changes. Docstring coverage check skipped.

      Poem

      I twitch my whiskers at version twenty-three, A hop in deps, a nimble server spree. Handlers awaken when each request bounds in, Lazy like lettuce, quick as a grin. Thump—deployment! My paws do a spin. 🥕🐇

      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.

      • Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.
      • Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.

      📜 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.yaml is 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)
      • examples/react/start-clerk-basic/package.json
      ⏰ 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
      ✨ Finishing Touches
      🧪 Generate unit tests
      • Create PR with unit tests
      • Post copyable unit tests in a comment

      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    2. View your CI Pipeline Execution ↗ for commit 4d189adde3c1fa8687f9513b9d880a76798cb895

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded1m 8sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded4sView ↗

      ☁️ Nx Cloud last updated this comment at 2025-09-10 16:37:36 UTC

    3. More templates

      @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@5026

      commit: 4d189ad

    4. Actionable 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.yaml is 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 legacy clerkHandler usage detected

      I ran a repository-wide search for any remaining calls to clerkHandler( and found no matches. All examples now consistently use the new handlerFactory pattern.


      15-18: Build Failure: Example’s Vite Config Missing Plugin The build is failing due to a missing @tanstack/react-start Vite plugin in the example’s node_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 build

      Once 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 build

      Length 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.ts

      Length 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
        import { tanstackStart } from '@tanstack/react-start/plugin/vite'
        errors at build time because @tanstack/react-start does not export a plugin/vite path.
      • Verify and correct the Vite plugin entrypoint in the @tanstack/react-start package (or adjust the import to the actual plugin location).
      • After fixing the import, confirm:
        • pnpm -w install completes with no unresolved peers
        • pnpm -F tanstack-start-example-clerk-basic run build succeeds without errors
    5. Some conflicts to be resolved

    6. Some conflicts to be resolved

      Fixed

Sign in to join this conversation.