chore(react-router): Accept organizationSyncOptions option in middleware

[wobsoriano]

Description

This PR adds the organizationSyncOptions option to React Router's clerkMiddleware().

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Added configurable organization sync options to the React Router middleware, enabling URL-based organization activation and customizable failure handling.
  • The organization sync option is now forwarded to authentication requests to ensure consistent organization state during auth flows.

• Documentation

  • Expanded docs with examples and guidance for URL patterns, activation flow, and error handling when using organization slugs.

[changeset-bot]

🦋 Changeset detected

Latest commit: 5025068

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/react-router	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Oct 5, 2025 3:46pm

[coderabbitai]

Walkthrough

The change adds an optional organizationSyncOptions property to ClerkMiddlewareOptions and forwards that option from loadOptions(...) into authenticateRequest(...) inside clerkMiddleware. No function signatures or return types changed; middleware control flow (handshake, headers, context, response) is unchanged.

Changes

Cohort / File(s)	Summary
Middleware integration packages/react-router/src/server/clerkMiddleware.ts	Forwards organizationSyncOptions from loadOptions(...) into clerkClient(args).authenticateRequest(...). No other control-flow or signature changes.
Type definitions packages/react-router/src/server/types.ts	Adds organizationSyncOptions?: OrganizationSyncOptions to ClerkMiddlewareOptions with documentation; consolidates internal type imports.
Changelog / docs .changeset/fresh-waves-sneeze.md	Documents the new organizationSyncOptions option, includes usage example and reference to guidance for organization slug URL patterns.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client
  participant Router
  participant clerkMiddleware
  participant ClerkBackend as Clerk Backend

  Client->>Router: HTTP Request
  Router->>clerkMiddleware: Invoke with request/context
  note over clerkMiddleware: loadOptions(args, options)\nmay include organizationSyncOptions
  clerkMiddleware->>ClerkBackend: authenticateRequest(request, { ..., organizationSyncOptions })
  alt Authenticated
    ClerkBackend-->>clerkMiddleware: RequestState (SignedIn/SignedOut)
    clerkMiddleware-->>Router: Continue with context set
    Router-->>Client: Response
  else Handshake/Redirect
    ClerkBackend-->>clerkMiddleware: Handshake/Redirect response
    clerkMiddleware-->>Client: Proxy handshake/redirect response
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my whiskers, options synced just right,
A tiny flag now journeys through the night.
Middleware hums, the headers stay aligned,
Organizations pop—precisely, well-defined.
I thump with joy: a tidy thread to sew,
One hop ahead, onward we go! 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title concisely highlights the primary change by indicating that the React Router middleware now accepts the organizationSyncOptions option. It follows conventional commit formatting and avoids extraneous details. This makes it clear and actionable for reviewers and future readers.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ 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 rob/org-sync-options-rr

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@6927

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@6927

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@6927

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@6927

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@6927

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@6927

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@6927

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@6927

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@6927

@clerk/express

npm i https://pkg.pr.new/@clerk/express@6927

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@6927

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@6927

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@6927

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@6927

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@6927

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@6927

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@6927

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@6927

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@6927

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@6927

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@6927

@clerk/types

npm i https://pkg.pr.new/@clerk/types@6927

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@6927

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@6927

commit: 5025068

[LauraBeatris]

Thanks for adding this to the react-router middleware! 🫡