feat(nextjs): Handle URL <> Session Org Mismatch in Middleware

[izaaklauer]

What problem is this solving?

Today, when developers use organization slugs in URLs, they need to go through contortions to be able to depend on the organization data in the clerk session, especially in server-rendered pages. In short, they need to detect the mismatch between the URL and the session on the server component, punt back to client-side javascript that can call setActive for the org as specified by the URL, and then re-render the server component. See some of that workflow here: https://clerk.com/docs/guides/force-organizations#set-an-active-organization-based-on-the-url

What changed?

This PR introduces a new NextJS middleware option that allows developers to specify their URL structure to the middleware - specifically which url patterns indicate a desire to activate the personal workspace or an organization, and if so which one (by slug or ID).

The middleware then checks the actual URL against that pattern, and if it detects a mismatch between the desired-active organization (from the url) and the actually-active organization (from the session), it performs a handshake with a new query param, which will activate the new organization.

What does the new API look like?

Imagine an application that supports organizations and the personal workspace, but includes both in their URLs. The might have URLs like:

URL	Indicates
/orgs/bcorp	org with slug "bcorp" should be active
/orgs/bcorp/settings	org with slug "bcorp" should be active
/personal-workspace/home	the personal workspace should be active

Currently, that application would require special handling in both server and client javascript to detect and resolve an organization mismatch.

Now, they can add middleware config like this:

import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isProtectedRoute = createRouteMatcher(["(.*)"]);

export default clerkMiddleware((auth, req) => {
  if (isProtectedRoute(req)) auth().protect();
}, {
  organizationSyncOptions: {
    organizationPatterns: [
      "/orgs/:slug",
      "/orgs/:slug/(.*)",
    ],
    personalWorkspacePatterns: [
      "/personal-workspace",
      "/personal-workspace/(.*)"
    ],
  },
});

What's next?

• A public-facing guide explaining the new guidance for managing an organization via the URL
• A public-facing sample repository demonstrating the new option

Further Reading:

Clerk internal DX guide: https://www.notion.so/clerkdev/Sync-Org-from-URL-to-Session-via-Middleware-f41f00865390480ab2279391c5625b27?pvs=4

[changeset-bot]

🦋 Changeset detected

Latest commit: bc89068

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

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

[izaaklauer]

My IDE automatically deleted all of these Test prefixes, citing this:

ESLint: should not have duplicate prefix(playwright/valid-title)

I can add them back if we like them though!

[LauraBeatris]

Suggested change

	* @returns {HandshakeState | SignedOutState | null} - The function can return the following:
	* - {HandshakeState}: If a handshake is needed to resolve the mismatched organization.
	* - {SignedOutState}: If a handshake is required but cannot be performed.
	* - {null}: If no action is required.
	*/
	* @returns {HandshakeState | SignedOutState | null} - The function can return the following:
	* - {HandshakeState}: If a handshake is needed to resolve the mismatched organization.
	* - {SignedOutState}: If a handshake is required but cannot be performed.
	* - {null}: If no action is required.
	*/

We can remove the @returns tag here since TypeScript already handles that for us.

[izaaklauer]

Is there a better place for me to give details on what each of those return types mean?

[panteliselef]

I think this is nice to have here, but it definitely needs to reach the customer facing documentation that we have as well.

[panteliselef]

Maybe there is a benefit of redefining those for the nextjs package and take advantage of our RouteMatcherWithNextTypedRoutes

[panteliselef]

And just to double check here, we don't wanna use the createRouteMatcher pattern here, because we are not expecting for folks to use more than one path ? Although the name of the properties hints that you can. If not, I think supporting the route matcher here makes sense.

cc @nikosdouvlis

[izaaklauer]

Good idea! I didn't realize we already have RouteMatcherParams, which serves the same purpose.

It looks like there's some duplication between the astro and nextjs RouteMatcherParams. My inclination here is to make the astro version (which doesn't depend on anything astro-specific) shared, and import that for use here. But let me know if you think another path would be better!

r/e createRouteMatcher - We could take a createRouteMatcher-returned function here too, but my inclination is to start with just accepting the pattern syntax for simplicity and expand the the more complex types if necessary in the future - I explored that a bit here (internal only): https://www.notion.so/Sync-Org-from-URL-to-Session-via-Middleware-f41f00865390480ab2279391c5625b27?d=f3738cb7f62c48bb90f8924c653a83a9&pvs=4#c0b57bf937694dd6bf510aeb4dde12af. Again, differing opinions welcome.

[izaaklauer]

Oh you know, digging in a bit further, I think the main difference here between this and RouteMatcherWithNextTypedRoutes/RouteMatcherRoutes is that they're geared at returning true/false, not pulling information out of the path. For the organization pattern, we need it to include a group (which I have here as :slug or :id). I don't see a clear way to extend the RouteMatcherParams to encompass that without making the type too complex for my taste. I could have the personal workspace pattern use RouteMatcherParams, but I think the mixed types would be worse DX.

And to answer your question:

we are not expecting for folks to use more than one path ?

I am expecting more than one path! It's very tricky to get most practical examples down to just one path expression, so I think allowing multiples is the way to go.

[brkalow]

One thing we've done in the past is pass options via request headers to avoid extra app overhead. Maybe this is something we can also do here?

[brkalow]

lgtm!