fix: modernize partner integration add-ons #490
main fromrefs/pull/490/head·merged by tannerlinsley Summary:
- move Clerk and WorkOS generators to their full-stack TanStack Start SDKs
- update Railway, Nitro, Sentry, Cloudflare, and pnpm 11 integration output
- preserve existing environment values and stop persisting secrets in .cta.json
- add focused generator coverage and a patch changeset for @tanstack/create
Validation:
- pnpm test
- fresh WorkOS app: TypeScript and production build
- fresh Clerk + Sentry + Railway app: TypeScript and production build
This supersedes the overlapping implementation work in #408 and #485.
Summary by CodeRabbit#
- New Features
- Modernized Clerk and WorkOS add-ons to use TanStack Start full-stack auth.
- Added WorkOS server callback + sign-in routes, and updated demo/header auth UI.
- Added CSRF-protected server middleware when auth add-ons are enabled.
- Improved Railway guidance to use Railpack with stable Nitro output.
- Bug Fixes
- Preserves existing
.env*values when updating generated projects. - Avoids overwriting sensitive config values and omits non-persisted env data.
- Safer Sentry defaults with reduced tracing/privacy exposure.
- Preserves existing
- Documentation
- Updated Clerk, WorkOS, and Railway setup/production instructions and environment variable templates.
- 1
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
Diff Package Supply Chain
SecurityVulnerability Quality Maintenance License nitro@3.0.260610-beta @workos/authkit-tanstack-react-start@0.11.0 @clerk/tanstack-react-start@1.4.21 @workos-inc/node@10.8.0 Actionable comments posted: 2
🧹 Nitpick comments (1)
packages/create/src/frameworks/solid/hosts/railway/package.json (1)
6-6: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winPin Nitro to a tested stable version.
"latest"makes generated Railway apps resolve different Nitro releases over time, so a scaffold can change behavior or stop building after a reinstall. Use the exact stable version covered by the Railway validation matrix and upgrade it deliberately.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/create/src/frameworks/solid/hosts/railway/package.json` at line 6, Update the Nitro dependency in the Railway host template package configuration from “latest” to the exact stable version covered by the Railway validation matrix, preserving deliberate version pinning for reproducible generated apps.🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/create/src/frameworks/react/add-ons/clerk/README.md`: - Around line 22-34: Update the README’s /dashboard beforeLoad example to call a createServerFn(...).handler(...) server function that performs auth() and returns the authorization or redirect state, rather than invoking auth() directly in beforeLoad. Keep the unauthenticated redirect behavior unchanged. In `@packages/create/src/frameworks/solid/add-ons/sentry/package.json`: - Line 3: Regenerate the Solid Sentry worker manifest represented by the generated add-on module so its emitted dependency matches the source manifest’s `@sentry/solid` version ^10.67.0. Update the generated output associated with the Solid Sentry add-on, preserving its existing structure and other dependency entries. --- Nitpick comments: In `@packages/create/src/frameworks/solid/hosts/railway/package.json`: - Line 6: Update the Nitro dependency in the Railway host template package configuration from “latest” to the exact stable version covered by the Railway validation matrix, preserving deliberate version pinning for reproducible generated apps.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
fd25ec76-17c9-4351-832d-aca5b49bdb44📥 Commits
Reviewing files that changed from the base of the PR and between 75db7e89a0a1125683bc75cca81acb700ef73eff and e0bc30755d3328fa4d8673b222944aac0ebdcea1.
📒 Files selected for processing (45)
.changeset/fresh-partner-paths.mdpackages/create/src/add-to-app.tspackages/create/src/config-file.tspackages/create/src/frameworks/react/add-ons/clerk/README.mdpackages/create/src/frameworks/react/add-ons/clerk/assets/_dot_env.local.appendpackages/create/src/frameworks/react/add-ons/clerk/assets/src/integrations/clerk/header-user.tsxpackages/create/src/frameworks/react/add-ons/clerk/assets/src/integrations/clerk/provider.tsxpackages/create/src/frameworks/react/add-ons/clerk/assets/src/routes/demo/clerk.tsxpackages/create/src/frameworks/react/add-ons/clerk/info.jsonpackages/create/src/frameworks/react/add-ons/clerk/package.jsonpackages/create/src/frameworks/react/add-ons/sentry/assets/instrument.server.mjspackages/create/src/frameworks/react/add-ons/sentry/info.jsonpackages/create/src/frameworks/react/add-ons/sentry/package.jsonpackages/create/src/frameworks/react/add-ons/workos/README.mdpackages/create/src/frameworks/react/add-ons/workos/assets/_dot_env.local.appendpackages/create/src/frameworks/react/add-ons/workos/assets/src/components/workos-user.tsxpackages/create/src/frameworks/react/add-ons/workos/assets/src/hooks/useUser.tsxpackages/create/src/frameworks/react/add-ons/workos/assets/src/integrations/workos/provider.tsxpackages/create/src/frameworks/react/add-ons/workos/assets/src/routes/api/auth/callback.tsxpackages/create/src/frameworks/react/add-ons/workos/assets/src/routes/api/auth/sign-in.tsxpackages/create/src/frameworks/react/add-ons/workos/assets/src/routes/demo/workos.tsxpackages/create/src/frameworks/react/add-ons/workos/info.jsonpackages/create/src/frameworks/react/add-ons/workos/package.jsonpackages/create/src/frameworks/react/hosts/cloudflare/package.json.ejspackages/create/src/frameworks/react/hosts/nitro/package.jsonpackages/create/src/frameworks/react/hosts/railway/README.mdpackages/create/src/frameworks/react/hosts/railway/assets/nixpacks.tomlpackages/create/src/frameworks/react/hosts/railway/info.jsonpackages/create/src/frameworks/react/hosts/railway/package.jsonpackages/create/src/frameworks/react/hosts/railway/package.json.ejspackages/create/src/frameworks/react/project/base/pnpm-workspace.yaml.ejspackages/create/src/frameworks/react/project/base/src/start.ts.ejspackages/create/src/frameworks/solid/add-ons/sentry/package.jsonpackages/create/src/frameworks/solid/hosts/cloudflare/package.json.ejspackages/create/src/frameworks/solid/hosts/nitro/package.jsonpackages/create/src/frameworks/solid/hosts/railway/README.mdpackages/create/src/frameworks/solid/hosts/railway/assets/nixpacks.tomlpackages/create/src/frameworks/solid/hosts/railway/info.jsonpackages/create/src/frameworks/solid/hosts/railway/package.jsonpackages/create/src/frameworks/solid/project/base/pnpm-workspace.yaml.ejspackages/create/src/types.tspackages/create/tests/add-to-app.test.tspackages/create/tests/config-file.test.tspackages/create/tests/edge-manifest.test.tspackages/create/tests/partner-addons.test.ts
💤 Files with no reviewable changes (4)
- packages/create/src/frameworks/react/hosts/railway/package.json
- packages/create/src/frameworks/react/hosts/railway/assets/nixpacks.toml
- packages/create/src/frameworks/react/add-ons/workos/assets/src/hooks/useUser.tsx
- packages/create/src/frameworks/solid/hosts/railway/assets/nixpacks.toml
@@ -24,12 +26,9 @@24-function ProtectedPage() {25- return (26- <>27- <SignedIn>28- <YourPageContent />29- </SignedIn>30- <SignedOut>31- <RedirectToSignIn />32- </SignedOut>33- </>34- )35-}26+import { createFileRoute, redirect } from '@tanstack/react-router'27+import { auth } from '@clerk/tanstack-react-start/server'28+29+export const Route = createFileRoute('/dashboard')({30+ beforeLoad: async () => {31+ const { userId } = await auth()32+ if (!userId) throw redirect({ to: '/' })33+ },34+})🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail # Inspect the target README and nearby Clerk add-on docs. git ls-files packages/create/src/frameworks/react/add-ons/clerk/README.md wc -l packages/create/src/frameworks/react/add-ons/clerk/README.md sed -n '1,120p' packages/create/src/frameworks/react/add-ons/clerk/README.md printf '\n--- search for createServerFn usage in related docs ---\n' rg -n "createServerFn|beforeLoad|auth\(\)" packages/create/src/frameworks/react -SRepository: TanStack/cli
Length of output: 9669
🏁 Script executed:
#!/bin/bash set -euo pipefail sed -n '1,120p' packages/create/src/frameworks/react/add-ons/clerk/README.md printf '\n--- adjacent Clerk docs ---\n' find packages/create/src/frameworks/react -path '*clerk*' -name '*.md' -maxdepth 8 -print | sortRepository: TanStack/cli
Length of output: 1746
🌐 Web query:
Clerk TanStack React Start auth createServerFn beforeLoad docs💡 Result:
To integrate Clerk authentication with TanStack Start using beforeLoad and createServerFn, follow these patterns established by official documentation. 1. Configuration: Install the official
@clerk/tanstack-react-startpackage [1][2]. Configure clerkMiddleware in your src/start.ts file within the requestMiddleware array [2][3]. 2. Server Function Pattern: Create a server function using createServerFn to retrieve and check authentication status [1][2]. The auth utility from@clerk/tanstack-react-start/serveris used to verify the user [1][4]. // src/server/auth.ts (Example) import { createServerFn } from '@tanstack/react-start'; import { auth } from '@clerk/tanstack-react-start/server'; import { redirect } from '@tanstack/react-router'; export const fetchAuthFn = createServerFn({ method: 'GET' }).handler(async => { const { userId, isAuthenticated } = await auth; if (!isAuthenticated) { throw redirect({ to: '/sign-in' }); } return { userId }; }); 3. Route Guard Pattern (beforeLoad): Use the beforeLoad property in your route definitions (or root route) to call the server function. This protects the route by ensuring authentication is verified before the page loads [2][4]. // src/routes/dashboard.tsx (Example) import { createFileRoute } from '@tanstack/react-router'; import { fetchAuthFn } from '../server/auth'; export const Route = createFileRoute('/dashboard')({ beforeLoad: async => await fetchAuthFn, component: DashboardComponent, }); Important Security Note: Documentation emphasizes that beforeLoad is primarily for route user experience (redirecting users away from unauthorized screens) [5][6]. It is not a data security boundary. You must protect your actual data by enforcing authorization (e.g., using authMiddleware) within every individual server function that reads or mutates private data [5][7][8]. For the easiest setup, use the Clerk CLI (clerk init), which automatically configures the necessary providers, middleware, and environment variables for your specific TanStack Start project [9].Citations:
- 1: https://tanstack.com/start/latest/docs/framework/react/examples/start-clerk-basic
- 2: https://clerk.com/docs/tanstack-react-start/getting-started/quickstart
- 3: https://clerk.com/docs/reference/tanstack-react-start/clerk-middleware
- 4: https://clerk.com/docs/tanstack-react-start/guides/users/reading
- 5: https://tanstack.com/start/latest/docs/framework/react/guide/authentication
- 6: https://tanstack.com/start/latest/docs/framework/react/guide/authentication-server-primitives
- 7: https://tanstack.com/start/latest/docs/framework/react/guide/server-functions
- 8: https://tanstack.com/start/v0/docs/framework/react/guide/middleware
- 9: https://clerk.com/articles/add-clerk-authentication-to-a-tanstack-start-app-with-the-clerk-cli
🌐 Web query:
TanStack Start beforeLoad server function createServerFn auth docs💡 Result:
In TanStack Start, route protection and data authorization are distinct concepts with different implementations [1][2]. Route
beforeLoadThebeforeLoadfunction is used for route-level User Experience (UX) to gate access to UI components [1][3]. It runs before a route is loaded, making it the appropriate place to check authentication status and redirect unauthorized users to a login page [1][3]. Example usage in a layout route: // routes/_authed.tsx import { createFileRoute, redirect } from '@tanstack/react-router' import { getCurrentUserFn } from '../server/auth' export const Route = createFileRoute('/_authed')({ beforeLoad: async ({ location }) => { const user = await getCurrentUserFn if (!user) { throw redirect({ to: '/login', search: { redirect: location.href }, }) } return { user } }, }) Important:beforeLoadis not a data security boundary [1][4][5]. Because server functions are independent API endpoints, they can be invoked directly by a client regardless of whether a user has visited the corresponding route [2][5][6]. Server Functions (createServerFn) and Auth To secure your data, you must apply authentication checks directly to the server functions that read or mutate private data [1][2][7]. The recommended approach is to use middleware [7][8]. Example of protecting a server function with middleware: import { createServerFn } from '@tanstack/react-start' import { authMiddleware } from '~/server/auth-middleware' export const getMyData = createServerFn({ method: 'GET' }).middleware([authMiddleware]).handler(async ({ context }) => { // context.session is populated by authMiddleware return db.data.findMany({ where: { userId: context.session.userId } }) }) Key Takeaways: - UsebeforeLoadfor UI-level access control and navigation [1][3]. - UseauthMiddlewareinsidecreateServerFnto establish a secure data boundary [1][7][5]. - Never rely on route guards to protect API endpoints [2][5][6].Citations:
- 1: https://tanstack.com/start/latest/docs/framework/react/guide/authentication
- 2: https://tanstack.com/start/latest/docs/framework/react/guide/server-functions
- 3: https://tanstack.com/router/v1/docs/guide/authenticated-routes.md
- 4: https://tanstack.com/start/latest/docs/framework/react/guide/authentication-server-primitives
- 5: https://github.com/TanStack/router/blob/main/packages/start-client-core/skills/start-core/auth-server-primitives/SKILL.md
- 6: https://tanstack.com/start/latest/docs/framework/react/guide/server-functions.md
- 7: https://tanstack.com/start/latest/docs/framework/react/guide/middleware
- 8: https://dev.to/hirotoshioi/how-to-protect-server-functions-with-auth-middleware-in-tanstack-start-opj
Call Clerk auth through a server function
beforeLoadshould invoke acreateServerFn(...).handler(...)that performsauth()and returns the redirect state; don’t callauth()directly from the route hook.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/create/src/frameworks/react/add-ons/clerk/README.md` around lines 22 - 34, Update the README’s /dashboard beforeLoad example to call a createServerFn(...).handler(...) server function that performs auth() and returns the authorization or redirect state, rather than invoking auth() directly in beforeLoad. Keep the unauthenticated redirect behavior unchanged.✅ Confirmed as addressed by @tannerlinsley
Fixed in 2a7e07fb. The example now calls Clerk auth inside a createServerFn handler and invokes that server function from beforeLoad.
@tannerlinsley, thanks for fixing this. The updated example now correctly keeps the Clerkauth()call in a server-function handler and invokes it frombeforeLoad.@@ -1,3 +1,3 @@11 {22 "dependencies": {3- "@sentry/solid": "^10.42.0"3+ "@sentry/solid": "^10.67.0"🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
rg -n -C2 '"`@sentry/solid`"' \ packages/create/src/frameworks/solid/add-ons/sentry/package.json \ packages/create/src/generated/worker/frameworks/solid/add-ons/sentry.tsRepository: TanStack/cli
Length of output: 1019
Regenerate the Solid Sentry worker manifest.
packages/create/src/generated/worker/frameworks/solid/add-ons/sentry.tsstill emits@sentry/solid: "^10.42.0", so generated apps won’t pick up the new^10.67.0dependency from the source manifest.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/create/src/frameworks/solid/add-ons/sentry/package.json` at line 3, Regenerate the Solid Sentry worker manifest represented by the generated add-on module so its emitted dependency matches the source manifest’s `@sentry/solid` version ^10.67.0. Update the generated output associated with the Solid Sentry add-on, preserving its existing structure and other dependency entries.The generated directory is intentionally ignored and recreated by the generate-manifest build step, so it is not a source artifact to commit. The commit hook regenerated it from the updated source manifest, then all builds and tests passed.
@tannerlinsley, understood—this generated directory is intentionally untracked and recreated bygenerate-manifest, so no generated worker manifest should be committed. I’m withdrawing this finding.
✏️ Learnings added
Learnt from: tannerlinsley Repo: TanStack/cli PR: 490 File: packages/create/src/frameworks/solid/add-ons/sentry/package.json:3-3 Timestamp: 2026-07-21T20:04:48.336Z Learning: In the TanStack CLI repository, `packages/create/src/generated` is intentionally ignored and recreated by the `generate-manifest` build step. Changes to source manifests (including add-on `package.json` files) must not require committing corresponding generated worker-manifest artifacts.Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
Fixed in 2a7e07fb. The example now calls Clerk auth inside a createServerFn handler and invokes that server function from beforeLoad.
The generated directory is intentionally ignored and recreated by the generate-manifest build step, so it is not a source artifact to commit. The commit hook regenerated it from the updated source manifest, then all builds and tests passed.
coderabbitai[bot](GitHub profile, opens in a new tab)replied on
packages/create/src/frameworks/react/add-ons/clerk/README.mdlines 22 to 40@tannerlinsley, thanks for fixing this. The updated example now correctly keeps the Clerkauth()call in a server-function handler and invokes it frombeforeLoad.coderabbitai[bot](GitHub profile, opens in a new tab)replied on
packages/create/src/frameworks/solid/add-ons/sentry/package.jsonline 3@tannerlinsley, understood—this generated directory is intentionally untracked and recreated bygenerate-manifest, so no generated worker manifest should be committed. I’m withdrawing this finding.
✏️ Learnings added
Learnt from: tannerlinsley Repo: TanStack/cli PR: 490 File: packages/create/src/frameworks/solid/add-ons/sentry/package.json:3-3 Timestamp: 2026-07-21T20:04:48.336Z Learning: In the TanStack CLI repository, `packages/create/src/generated` is intentionally ignored and recreated by the `generate-manifest` build step. Changes to source manifests (including add-on `package.json` files) must not require committing corresponding generated worker-manifest artifacts.Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
tannerlinsley merged thisfb59492
tannerlinsley closed this
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
e835bba1-3b29-4828-a19e-266efa9af4ae📥 Commits
Reviewing files that changed from the base of the PR and between e0bc30755d3328fa4d8673b222944aac0ebdcea1 and 2a7e07fb6ab87f6b8d55b19372717cb8de5235d9.
📒 Files selected for processing (6)
packages/create/src/frameworks/react/add-ons/clerk/README.mdpackages/create/src/frameworks/react/hosts/nitro/package.jsonpackages/create/src/frameworks/react/hosts/railway/package.json.ejspackages/create/src/frameworks/solid/hosts/nitro/package.jsonpackages/create/src/frameworks/solid/hosts/railway/package.jsonpackages/create/tests/partner-addons.test.ts🚧 Files skipped from review as they are similar to previous changes (5)
📝 Walkthrough
Walkthrough#
The PR modernizes generated Clerk and WorkOS integrations for TanStack Start, preserves existing environment values, removes persisted secret values, updates Railway and pnpm templates, changes Sentry defaults, and adds scaffold-generation tests.
Changes#
Partner add-on modernization
packages/create/src/add-to-app.ts,packages/create/src/config-file.ts,packages/create/tests/*envVarValuesis excluded from persisted configuration.packages/create/src/frameworks/react/add-ons/clerk/*,packages/create/tests/*packages/create/src/frameworks/react/add-ons/workos/*,packages/create/tests/partner-addons.test.tspackages/create/src/frameworks/*/hosts/*,packages/create/src/frameworks/*/project/base/*,packages/create/src/types.ts,packages/create/tests/partner-addons.test.tspackages/create/src/frameworks/*/add-ons/sentry/*,packages/create/tests/partner-addons.test.tsEstimated code review effort: 4 (Complex) | ~45 minutes
Sequence Diagram(s)#
Possibly related PRs
AddOnBaseSchemacontract.Suggested reviewers:
schiller-manuel🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ Finishing Touches
📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning
There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.
🔧 ESLint
packages/create/tests/partner-addons.test.ts
Parsing error: "parserOptions.project" has been provided for
@typescript-eslint/parser. The file was not found in any of the provided project(s): packages/create/tests/partner-addons.test.tsComment `@coderabbitai help` to get the list of available commands.