Add organizationSyncOptions prop to clerkMiddleware() options #1634
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
izaaklauer
commented
Oct 17, 2024
Comment on lines
346
to
377
| - `signInUrl?` | ||
| - `publishableKey` | ||
| - `string` | ||
|
|
||
| An alternative sign in URL. | ||
| The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. | ||
|
|
||
| --- | ||
|
|
||
| - `signUpUrl?` | ||
| - `secretKey?` | ||
| - `string` | ||
|
|
||
| An alternative sign up URL. | ||
| The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option, refer to [Dynamic keys](#dynamic-keys). | ||
|
|
||
| --- | ||
|
|
||
| - `publishableKey` | ||
| - `signInUrl?` | ||
| - `string` | ||
|
|
||
| The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. | ||
| An alternative sign in URL. | ||
|
|
||
| --- | ||
|
|
||
| - `secretKey?` | ||
| - `signUpUrl?` | ||
| - `string` | ||
|
|
||
| The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option, refer to [Dynamic keys](#dynamic-keys). | ||
| An alternative sign up URL. |
There was a problem hiding this comment.
This is all just a re-arrangement - I noticed that the list was almost alphabetized, and now it's alphabetized.
mzhong9723
reviewed
Oct 17, 2024
| URL patterns that are organization-specific and contain an organization ID or slug as a path parameter. If a request | ||
| matches this path, the organization identifier will be extracted and activated before rendering. | ||
|
|
||
| If the route also matches the personalAccountPatterns, this takes precedence. |
There was a problem hiding this comment.
🔧 Can we have personalAccountPatterns appear with in-line code formatting, or even link to the definition?
There was a problem hiding this comment.
Comment on lines
467
to
469
| > no change will be made to the previously active organization. Components must detect this case and respond with an | ||
| > appropriate error (e. g., `notFound()`, an | ||
| > [organization switcher](/docs/components/organization/organization-switcher), etc.). |
There was a problem hiding this comment.
🔧 This sentence and examples in parentheses was confusing to me, because responding by rendering the org switcher doesn't seem to fall into the category of an appropriate error
There was a problem hiding this comment.
How does that feel?
Comment on lines
471
to
474
| Common examples: | ||
| - `["/orgs/:slug", "/orgs/:slug/(.*)"]` | ||
| - `["/orgs/:id", "/orgs/:id/(.*)"]` | ||
| - `["/app/:any/orgs/:slug", "/app/:any/orgs/:slug/(.*)"]` |
There was a problem hiding this comment.
❓ Would it be helpful to provide some examples that would match these?
There was a problem hiding this comment.
Oh I just saw the section on Patterns, so maybe this isn't as necessary
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/1634 |
Co-authored-by: Mary Zhong <[email protected]>
It causes our linter to fail: https://github.com/clerk/clerk-docs/actions/runs/11462466478/job/31893925923?pr=1634 it'd be nice if the linter allowed for glossary links, but i'm not going to move that boulder today.
alexisintech
approved these changes
Oct 23, 2024
alexisintech
changed the title
alexisintech
changed the title
victoriaxyz
reviewed
Oct 25, 2024
victoriaxyz
reviewed
Oct 25, 2024
victoriaxyz
requested changes
Oct 25, 2024
Co-authored-by: victoria <[email protected]>
izaaklauer
force-pushed
the
izaak/orgs-132-document-org-sync-middleware-options
branch
from
b273bfa
to
7c750bc
Compare
Co-authored-by: victoria <[email protected]>
Co-authored-by: victoria <[email protected]>
|
Thank you @victoriaxyz for those improvements! |
victoriaxyz
reviewed
Oct 28, 2024
victoriaxyz
reviewed
Oct 28, 2024
victoriaxyz
reviewed
Oct 28, 2024
victoriaxyz
reviewed
Oct 28, 2024
victoriaxyz
reviewed
Oct 28, 2024
Co-authored-by: victoria <[email protected]>
Co-authored-by: victoria <[email protected]>
Co-authored-by: victoria <[email protected]>
victoriaxyz
requested changes
Oct 29, 2024
Co-authored-by: victoria <[email protected]>
Co-authored-by: victoria <[email protected]>
Co-authored-by: victoria <[email protected]>
This reverts commit 0220928. Decided that we like the personal account highlight. Here's my justification for any future readers who are interested In general, our section links are quite good - the section title we link to makes it clear that the article is talking about the term of interest. In this case, we don't have a "personal account" definition to jump to with a section link. As a user, if I was promised the definition of Personal Account and the link went to https://clerk.com/docs/organizations/organization-workspaces#organization-workspaces-in-the-clerk-dashboard, there's a good chance i'd read the long title and think "ugh, I don't want to read up on the complete theory of organization workspaces in the dashboard right now thank you", and navigate away. I think the text highlight would point me to the part i'm actually interested in! It's a little bit brittle though - if we restructure the page in the future so that the first appearance of "Personal account" isn't the definition, this will seem broken. Tradeoffs! I think it's worth it in this case, but not a big deal either way.
This reverts commit e9ff7c3. We like the test highlighting after all. My justification for anyone interested: In general, our section links are quite good - the section title we link to makes it clear that the article is talking about the term of interest. In this case, we don't have a "personal account" definition to jump to with a section link. As a user, if I was promised the definition of Personal Account and the link went to https://clerk.com/docs/organizations/organization-workspaces#organization-workspaces-in-the-clerk-dashboard, there's a good chance i'd read the long title and think "ugh, I don't want to read up on the complete theory of organization workspaces in the dashboard right now thank you", and navigate away. I think the text highlight would point me to the part i'm actually interested in! It's a little bit brittle though - if we restructure the page in the future so that the first appearance of "Personal account" isn't the definition, this will seem broken. Tradeoffs! I think it's worth it in this case, but not a big deal either way.
After actually digesting https://clerk.com/docs/organizations/organization-workspaces#organization-workspaces-in-the-clerk-dashboard, i think that's probably not the best thing to link to! The use-case i'm talking to isn't about the dashboard at all - it's building custom apps. The dashboard happens to consume this feature also, so it has "personal accounts", but those docs are specifically about what personal accounts mean to the dashboard, not to any application.
victoriaxyz
approved these changes
Oct 31, 2024
alexisintech
reviewed
Nov 1, 2024
| - `organizationSyncOptions?` | ||
| - <code>[OrganizationSyncOptions](#organization-sync-options) | undefined</code> | ||
|
|
||
| Used to activate a specific [organization](docs/organizations/overview) or [personal account](https://clerk.com/glossary#personal-account) 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. |
There was a problem hiding this comment.
Suggested change
| Used to activate a specific [organization](docs/organizations/overview) or [personal account](https://clerk.com/glossary#personal-account) 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. | |
| 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. |
| - `string` | ||
|
|
||
| An alternative sign up URL. | ||
| The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option. For more information, refer to [Dynamic keys](#dynamic-keys) section. |
There was a problem hiding this comment.
Suggested change
| The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option. For more information, refer to [Dynamic keys](#dynamic-keys) section. | |
| The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option. For more information, refer to the [Dynamic keys](#dynamic-keys) section. |
| 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 [organization switcher](/docs/components/organization/organization-switcher). |
There was a problem hiding this comment.
Suggested change
| > 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 [organization switcher](/docs/components/organization/organization-switcher). | |
| > 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). |
| - <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 extracted and activated before rendering. |
There was a problem hiding this comment.
when you say "the organization identifier will be activated", do you mean the organization identifier will be used to set that org as active?
| - `personalAccountPatterns` | ||
| - <code>[Pattern](#pattern)\[]</code> | ||
|
|
||
| URL patterns for resources that exist within the context of a [Clerk Personal Account](https://clerk.com/glossary#personal-account) (user-specific, outside any |
There was a problem hiding this comment.
Suggested change
| URL patterns for resources that exist within the context of a [Clerk Personal Account](https://clerk.com/glossary#personal-account) (user-specific, outside any | |
| 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 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Depends on the release of clerk/javascript#4320
Preview
https://clerk.com/docs/pr/1634/references/nextjs/clerk-middleware#clerk-middleware-next-js
What changed?
This PR documents a new middleware option introduced in clerk/javascript#3977
What's next?