Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add organizationSyncOptions prop to clerkMiddleware() options #1634

Merged
merged 33 commits into from
Dec 20, 2024
Merged
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
e319c32
Alphabetizing middleware options
izaaklauer Oct 17, 2024
36cbef2
Documenting organizationSyncOptions
izaaklauer Oct 17, 2024
76ceb1b
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 21, 2024
73ce834
Responding to https://github.com/clerk/clerk-docs/pull/1634/files#r18…
izaaklauer Oct 21, 2024
ff0d75e
Code formatting
izaaklauer Oct 21, 2024
39f784d
Running `npm run format`
izaaklauer Oct 22, 2024
a3e531a
Not relative linking to the glossary.
izaaklauer Oct 22, 2024
88b32cd
code review
alexisintech Oct 23, 2024
607f55a
Merge branch 'main' into izaak/orgs-132-document-org-sync-middleware-…
victoriaxyz Oct 25, 2024
7c750bc
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 25, 2024
cf341d2
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 25, 2024
21a34ee
Apply suggestions from code review
izaaklauer Oct 25, 2024
c1e6f67
Merge branch 'main' into izaak/orgs-132-document-org-sync-middleware-…
victoriaxyz Oct 28, 2024
90ad16d
Repointing personal account links
izaaklauer Oct 29, 2024
0b2bc40
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 29, 2024
57e7acd
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 29, 2024
176c50d
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 29, 2024
109cca9
Merge branch 'main' into izaak/orgs-132-document-org-sync-middleware-…
victoriaxyz Oct 30, 2024
206ed7c
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 30, 2024
e9ff7c3
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 30, 2024
0220928
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Oct 30, 2024
77fbfc1
Update docs/references/nextjs/clerk-middleware.mdx
victoriaxyz Oct 30, 2024
828f7fa
Revert "Update docs/references/nextjs/clerk-middleware.mdx"
izaaklauer Oct 30, 2024
152dcb0
Revert "Update docs/references/nextjs/clerk-middleware.mdx"
izaaklauer Oct 30, 2024
fa1c4a5
Reverting all the way back to the glossary.
izaaklauer Oct 30, 2024
1a6766b
Merge branch 'main' into izaak/orgs-132-document-org-sync-middleware-…
victoriaxyz Oct 31, 2024
bad272c
Merge branch 'main' into izaak/orgs-132-document-org-sync-middleware-…
victoriaxyz Nov 1, 2024
c7662b2
Update docs/references/nextjs/clerk-middleware.mdx
izaaklauer Dec 18, 2024
ecdb743
Apply suggestions from code review
izaaklauer Dec 18, 2024
365e075
Merge branch 'main' into izaak/orgs-132-document-org-sync-middleware-…
izaaklauer Dec 18, 2024
9eac798
Removing rouge formatting change
izaaklauer Dec 18, 2024
e26600d
Addressing https://github.com/clerk/clerk-docs/pull/1634#discussion_r…
izaaklauer Dec 18, 2024
75a9f87
format
alexisintech Dec 18, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions docs/references/nextjs/clerk-middleware.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -338,6 +338,13 @@ The `clerkMiddleware()` function accepts an optional object. The following optio

---

- `organizationSyncOptions?`
- <code>[OrganizationSyncOptions](#organization-sync-options) | undefined</code>

Used to activate a specific [organization](docs/organizations/overview) or [personal account](/docs/organizations/organization-workspaces#organization-workspaces-in-the-clerk-dashboard:~:text=Personal%20account) based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by [`auth()`](/docs/references/nextjs/auth)) and the organization indicated by the URL, the middleware will attempt to activate the organization specified in the URL.
izaaklauer marked this conversation as resolved.
Show resolved Hide resolved

---

- `proxyUrl?`
- `string`

Expand Down Expand Up @@ -430,3 +437,75 @@ export default clerkMiddleware(
},
)
```

### `OrganizationSyncOptions`

The `organizationSyncOptions` property on the [`clerkMiddleware()`](#clerk-middleware-options) options
object has the type `OrganizationSyncOptions`, which has the following properties:

<Properties>
- `organizationPatterns`
- <code>[Pattern](#pattern)\[]</code>

Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request
matches this path, the organization identifier will be used to set that org as active.

If the route also matches the `personalAccountPatterns` prop, this prop takes precedence.

Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).

> [!WARNING]
> If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](/docs/components/organization/organization-switcher).

Common examples:

- `["/orgs/:slug", "/orgs/:slug/(.*)"]`
- `["/orgs/:id", "/orgs/:id/(.*)"]`
- `["/app/:any/orgs/:slug", "/app/:any/orgs/:slug/(.*)"]`

---

- `personalAccountPatterns`
- <code>[Pattern](#pattern)\[]</code>

URL patterns for resources that exist within the context of a [Clerk Personal Account](/docs/organizations/organization-workspaces#organization-workspaces-in-the-clerk-dashboard:~:text=Personal%20account) (user-specific, outside any
izaaklauer marked this conversation as resolved.
Show resolved Hide resolved
organization).

If the route also matches the `organizationPattern` prop, the `organizationPattern` prop takes precedence.

Common examples:

- `["/me", "/me/(.*)"]`
- `["/user/:any", "/user/:any/(.*)"]`
</Properties>

### Pattern

A `Pattern` is a `string` that represents the structure of a URL path. In addition to any valid URL, it may include:

- Named path parameters prefixed with a colon (e.g., `:id`, `:slug`, `:any`).
- Wildcard token, `(.*)`, which matches the remainder of the path.

#### Examples

- `/orgs/:slug`

| URL | Matches | `:slug` value |
| - | - | - |
| `/orgs/acmecorp` | ✅ | `acmecorp` |
| `/orgs` | ❌ | n/a |
| `/orgs/acmecorp/settings` | ❌ | n/a |

- `/app/:any/orgs/:id`

| URL | Matches | `:id` value |
| - | - | - |
| `/app/petstore/orgs/org_123` | ✅ | `org_123` |
| `/app/dogstore/v2/orgs/org_123` | ❌ | n/a |

- `/personal-account/(.*)`

| URL | Matches |
| - | - |
| `/personal-account/settings` | ✅ |
| `/personal-account` | ❌ |
Loading