@clerk/upgrade 0.2.0 → 0.3.0

package/dist/guide-generators/v5/retheme/__output.mdx

@@ -0,0 +1,437 @@
+---
+title: "Redesigned Components in v5"
+description: "Learn how to handle changes as a result of redesigned components in Clerk version 5"
+---
+
+# Redesigned Components in v5
+
+The new version ships with improved design and UX across all of Clerk's [UI components](/docs/components/overview). If you have used the [`appearance` prop](/docs/components/customization/overview) or tokens for a [custom theme](/docs/components/customization/overview#create-a-custom-theme), you will likely need to make some adjustments to ensure your styling is still looking great. If you're using the [localization prop](/docs/components/customization/localization) you will likely need to make adjustments to account for added or removed localization keys.
+
+<Callout type='info'>
+  If you are not customizing the appearance of your components, or using `localization`, you can skip this section. If
+  you are, we recommend using our CLI (`npx @clerk/upgrade`) to scan for changes required as part of the component
+  redesign more quickly.
+</Callout>
+
+The sections below contain more info on each change made to the customization ids and localization keys for reference. Regardless of how thoroughly you have reviewed the following information, we still recommend that you ensure that you have taken some time to manually look through each of your views to ensure that everything looks good still.
+
+## Appearance Changes
+
+<Accordion titles={["<code>Settings</code> -&gt; <code>General</code> tab in <code>OrganizationProfile</code>", "Within <code>&lt;UserProfile /&gt;</code>, Account and Security Pages Separated", "Within <code>&lt;UserProfile /&gt;</code>, Multi-Factor Auth is Added via Dropdown", "Within <code>&lt;UserProfile /&gt;</code>, Connected Accounts Added via Dropdown", "<code>userButtonPopoverActionButtonText</code> customization id removed", "<code>userButtonBox</code> is now a child of <code>userButtonTrigger</code>", "<code>organizationSwitcherPopoverActionButtonText</code> customization id removed", "Changes to the <code>card</code> customization id", "Back button customization ids change on alternative 2fa methods page", "<code>button</code> -&gt; <code>organizationListCreateOrganizationActionButton</code> customization id", "<code>socialButtonsBlockButtonArrow</code> customization id removed", "Identity preview avatar customization ids removed", "Changes to default variables"]}>
+  <AccordionPanel>    
+    The "Settings" tab within the `<OrganizationProfile />` component has been renamed to "General". If you are linking directly to `/organization-settings` from anywhere, the link will need to be updated to `/organization-general`.
+    
+    If you are [customizing the component](https://clerk.com/docs/components/customization/organization-profile) by re-ordering the pages, the label used to target this page must be changed from `settings` to `general` as well.
+    
+    If you are using the [appearance prop](https://clerk.com/docs/components/customization/overview) to customize the appearance of the `<OrganizationProfile />` component, please note that the `cl-profilePage__organizationSettings` key has also been changed to `cl-profilePage__organizationGeneral` to be consistent with the naming change.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Within the `<UserProfile />` component (which is also rendered by `<UserButton />`), the "Account" and "Security" pages now live within their own tabs. Previously, "Security" was a section within the "Account" tab. The "Security" page can now be directly linked to under the `/security` path if desired.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Within the `<UserProfile />` component (which is also rendered by `<UserButton />`), adding a multi-factor auth (MFA) method is now rendered as a dropdown instead of a modal. If you were relying on the modal for any sort of customizations, these customizations will need to be adjusted to the new form factor.
+    
+    Two new appearance prop keys were added to aid with this process: `cl-menuList__mfa` for styling the list of MFA factors, and `cl-menuItem__mfa` for styling individual items.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Within the `<UserProfile />` component (which is also rendered by `<UserButton />`), adding a connected account is now rendered as a dropdown instead of a modal. If you were relying on the modal for any sort of customizations, these customizations will need to be adjusted to the new form factor.
+    
+    New appearance prop keys were added to aid with customization, if desired:
+    
+    - `cl-menuList__connectedAccounts` for styling the list of connected account addition options
+    - `cl-menuItem__connectedAccounts` for styling individual items in the connected account options list
+    - `cl-menuList__web3Wallets` for styling the list of web3 wallet addition options
+    - `cl-menuItem__web3Wallets` for styling individual items in the web3 wallets options list
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `userButtonPopoverActionButtonText` customization id has been removed, as the text for this button is now directly rendered inside the button rather than an extra wrapping element. The nested ids `userButtonPopoverActionButtonText__signOut` and `userButtonPopoverActionButtonText__manageAccount` have also been removed. Any styling that needs to apply to the text can be applied to its direct parent `cl-userButtonPopoverActionButton`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The parent-child relationship of the two elements `userButtonTrigger` and `userButtonBox` has been swapped. Previously, `userButtonTrigger` was nested inside of `userButtonBox`, and now `userButtonBox` is nested inside of `userButtonTrigger`. This change resolves [some usability issues](https://github.com/clerk/javascript/issues/1625) in `<UserButton />`. If you are applying style customization to either of these elements, your customizations may need to be adjusted.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `organizationSwitcherPopoverActionButtonText` customization id has been removed, as the text for this button is now directly rendered inside the button rather than an extra wrapping element. The nested ids `organizationSwitcherPopoverActionButtonText__manageOrganization` and `organizationSwitcherPopoverActionButtonText__createOrganization` have also been removed. Any styling that needs to apply to the text can be applied to its direct parent `cl-organizationSwitcherPopoverActionButton`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `card` customization id in the previous major version was the main and only container element for components. Outside the `card` element, a new `cardBox` id was introduced that allows more fine-grained style customization.
+    
+    As a note, if you are changing the background color of `card`, you will also need to also apply the same color on the `footer` id as well. The `footer` now gray by default, and it’s located outside `card`, but inside `cardBox`.
+    
+    A `footerItem` id was also added for more targeted styling of items inside the `footer`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The "back" button on the panel within `<SignIn />` that lists out alternative two factor auth methods has changed location, and there have been some changes to the ids as a result of this:
+    
+    - `headerBackIcon` has been removed, as there is no longer an associated icon
+    - `headerBackRow` has been renamed to `backRow` as it's no longer in the header
+    - `headerBackLink` has been renamed to `backLink` as it's no longer in the header
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `button` customization id was used only in one place, for a button to create a new organization in the `<OrganizationList />` component. This id has been removed and replaced by the more appropriately named `organizationListCreateOrganizationActionButton` customization id instead.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Social sign-in buttons in the new component designs no longer include arrows, so the `socialButtonsBlockButtonArrow` customization id has been removed. You can use the `socialButtonsIconButton` to apply custom styling to the social buttons if desired.
+  </AccordionPanel>
+  <AccordionPanel>    
+    When signing in with Clerk's `<SignIn />` component, after entering a username or email the user is brought to a second pane where they can enter a second factor such as a password. On this pane, there is an area called "identity preview" that shows the username/email that they are entering a password/etc for. Previously, this area included the user's avatar, but this is no longer the case in updated designs. As such, the customization ids related to the user's avatar have been removed.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The default values of some [appearance variables](/docs/components/customization/variables) have changed which may impact your UI (if you are not already overriding them).
+    
+        - The default `colorPrimary` value changed from `#103FEF` to `#2F3037`. As the new color is a dark grey, the `colorPrimary` of the dark theme was changed to `#FFFFFF`.
+        - The default `fontSize` value changed from `1rem` to `0.8125rem`
+        - The default `fontWeight` values changed from `{ normal: 400, medium: 500, bold: 600 }` to `{ normal: 400, medium: 500, bold: 700 }`
+        - Previously, the default value for `fontSmoothing` was `auto`. This value is now unset. If you want to pass a custom value to it, you can still do so.
+  </AccordionPanel>
+</Accordion>
+
+## Localization Changes
+
+<Accordion titles={["New localization keys added", "Removed localization keys", "Localization keys changed"]}>
+  <AccordionPanel>    
+    As part of the redesign of Clerk's components, a number of new localization keys have been added and can be seen along with their default english values in the code block below. If you do not supply translated values for these keys in your custom localization, they will fall back to the default english values specified below.
+    
+    ```js
+    const newValues = {
+      formFieldLabel__organizationName: 'Name',
+      formFieldLabel__organizationSlug: 'Slug',
+      formFieldInputPlaceholder__emailAddresses: 'example@email.com, example2@email.com',
+      formFieldInputPlaceholder__organizationSlug: 'my-org',
+      signUp: {
+        start: {
+          subtitle: 'Welcome! Please fill in the details to get started.',
+          actionText: 'Already have an account?',
+        },
+        emailCode: {
+          subtitle: 'Enter the verification code sent to your email',
+        },
+        phoneCode: {
+          subtitle: 'Enter the verification code sent to your phone',
+        },
+        continue: {
+          subtitle: 'Please fill in the remaining details to continue.',
+          actionText: 'Already have an account?',
+        },
+      },
+      signIn: {
+        start: {
+          title: 'Sign in to {{applicationName}}',
+          subtitle: 'Welcome back! Please sign in to continue',
+          actionText: 'Don’t have an account?',
+        },
+        password: {
+          subtitle: 'Enter the password associated with your account',
+        },
+        forgotPasswordAlternativeMethods: {
+          label__alternativeMethods: 'Or, sign in with another method',
+        },
+        resetPassword: {
+          title: 'Set new password',
+        },
+        phoneCodeMfa: {
+          subtitle: 'To continue, please enter the verification code sent to your phone',
+        },
+        totpMfa: {
+          subtitle: 'To continue, please enter the verification code generated by your authenticator app',
+        },
+        backupCodeMfa: {
+          subtitle: 'Your backup code is the one you got when setting up two-step authentication.',
+        },
+      },
+      userProfile: {
+        formButtonPrimary__continue: 'Save',
+        start: {
+          headerTitle__account: 'Profile details',
+          profileSection: {
+            primaryButton: 'Edit profile',
+          },
+          emailAddressesSection: {
+            detailsAction__unverified: 'Verify',
+            destructiveAction: 'Remove email',
+          },
+          mfaSection: {
+            phoneCode: {
+              destructiveActionLabel: 'Remove',
+            },
+            backupCodes: {
+              actionLabel__regenerate: 'Regenerate',
+            },
+          },
+          dangerSection: {
+            title: 'Account termination',
+            deleteAccountButton: 'Delete account',
+          },
+        },
+        profilePage: {
+          imageFormSubtitle: 'Upload',
+          imageFormDestructiveActionSubtitle: 'Remove',
+        },
+        phoneNumberPage: {
+          title: 'Add a phone number',
+          infoText:
+            'A text message containing a verification link will be sent to this phone number. Message and data rates may apply.',
+        },
+        connectedAccountPage: {
+          socialButtonsBlockButton: '{{provider|titleize}}',
+        },
+        mfaPhoneCodePage: {
+          subtitle__availablePhoneNumbers:
+            'Select an existing phone number to register for SMS code two-step verification or add a new one.',
+          subtitle__unavailablePhoneNumbers:
+            'There are no available phone numbers to register for SMS code two-step verification, please add a new one.',
+        },
+        deletePage: {
+          actionDescription: 'Type "Delete account" below to continue.',
+        },
+      },
+      organizationSwitcher: {
+        action__createOrganization: 'Create organization',
+        action__manageOrganization: 'Manage',
+      },
+      organizationProfile: {
+        profilePage: {
+          title: 'Update Profile',
+          dangerSection: {
+            title: 'Danger',
+            leaveOrganization: {
+              actionDescription: 'Type "{{organizationName}}" below to continue.',
+            },
+            deleteOrganization: {
+              actionDescription: 'Type "{{organizationName}}" below to continue.',
+            },
+          },
+        },
+        invitePage: {
+          title: 'Invite new members',
+          subtitle: 'Enter or paste one or more email addresses, separated by spaces or commas.',
+        },
+      },
+      createOrganization: {
+        title: 'Create organization',
+      },
+      organizationList: {
+        title: 'Choose an account',
+        titleWithoutPersonal: 'Choose an organization',
+      },
+    };
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    As part of the redesign of Clerk's components, a number of localization keys have been removed as they were no longer present in the new designs. You should remove any of these keys that are present in your localization object as they are no longer needed.
+    
+    ```js
+    const deletedKeys = [
+      'signIn.forgotPassword.title_email',
+      'signIn.forgotPassword.title_phone',
+      'signIn.forgotPassword.formSubtitle_email',
+      'signIn.forgotPassword.formSubtitle_phone',
+      'signIn.emailCode.formSubtitle',
+      'signIn.phoneCode.formSubtitle',
+      'signIn.phoneCodeMfa.formSubtitle',
+      'signIn.totpMfa.formSubtitle',
+      'signIn.backupCodeMfa.formTitle',
+      'signIn.backupCodeMfa.formSubtitle',
+      'userProfile.start.emailAddressesSection.detailsTitle__primary',
+      'userProfile.start.emailAddressesSection.detailsSubtitle__primary',
+      'userProfile.start.emailAddressesSection.detailsTitle__nonPrimary',
+      'userProfile.start.emailAddressesSection.detailsSubtitle__nonPrimary',
+      'userProfile.start.emailAddressesSection.detailsTitle__unverified',
+      'userProfile.start.emailAddressesSection.detailsSubtitle__unverified',
+      'userProfile.start.emailAddressesSection.destructiveActionTitle',
+      'userProfile.start.emailAddressesSection.destructiveActionSubtitle',
+      'userProfile.start.phoneNumbersSection.detailsTitle__primary',
+      'userProfile.start.phoneNumbersSection.detailsSubtitle__primary',
+      'userProfile.start.phoneNumbersSection.detailsTitle__nonPrimary',
+      'userProfile.start.phoneNumbersSection.detailsSubtitle__nonPrimary',
+      'userProfile.start.phoneNumbersSection.detailsTitle__unverified',
+      'userProfile.start.phoneNumbersSection.detailsSubtitle__unverified',
+      'userProfile.start.phoneNumbersSection.destructiveActionTitle',
+      'userProfile.start.phoneNumbersSection.destructiveActionSubtitle',
+      'userProfile.start.connectedAccountsSection.title__conectionFailed',
+      'userProfile.start.connectedAccountsSection.title__connectionFailed',
+      'userProfile.start.connectedAccountsSection.title__reauthorize',
+      'userProfile.start.connectedAccountsSection.subtitle__reauthorize',
+      'userProfile.start.connectedAccountsSection.actionLabel__conectionFailed',
+      'userProfile.start.connectedAccountsSection.destructiveActionSubtitle',
+      'userProfile.start.connectedAccountsSection.destructiveActionAccordionSubtitle',
+      'userProfile.start.mfaSection.phoneCode.destructiveActionTitle',
+      'userProfile.start.mfaSection.phoneCode.destructiveActionSubtitle',
+      'userProfile.start.mfaSection.phoneCode.title__default',
+      'userProfile.start.mfaSection.phoneCode.title__setDefault',
+      'userProfile.start.mfaSection.phoneCode.subtitle__default',
+      'userProfile.start.mfaSection.phoneCode.subtitle__setDefault',
+      'userProfile.start.mfaSection.totp.title',
+      'userProfile.start.mfaSection.totp.subtitle',
+      'userProfile.start.mfaSection.totp.destructiveActionSubtitle',
+      'userProfile.start.mfaSection.totp.destructiveActionLabel',
+      'userProfile.start.activeDevicesSection.primaryButton',
+      'userProfile.start.activeDevicesSection.detailsTitle',
+      'userProfile.start.activeDevicesSection.detailsSubtitle',
+      'userProfile.start.activeDevicesSection.destructiveActionTitle',
+      'userProfile.start.activeDevicesSection.destructiveActionSubtitle',
+      'userProfile.start.web3WalletsSection.destructiveActionTitle',
+      'userProfile.start.web3WalletsSection.destructiveActionSubtitle',
+      'userProfile.start.dangerSection.deleteAccountTitle',
+      'userProfile.start.dangerSection.deleteAccountDescription',
+      'userProfile.start.headerSubtitle__account',
+      'userProfile.start.headerSubtitle__security',
+      'organizationProfile.start.headerTitle__settings',
+      'organizationProfile.start.headerSubtitle__members',
+      'organizationProfile.start.headerSubtitle__settings',
+      'organizationProfile.profilePage.domainSection.unverifiedDomain_menuAction__verify',
+      'organizationProfile.profilePage.domainSection.unverifiedDomain_menuAction__remove',
+      'organizationProfile.profilePage.subtitle',
+      'organizationProfile.membersPage.start.headerTitle__active',
+      'organizationProfile.membersPage.start.headerTitle__invited',
+      'createOrganization.subtitle',
+      'formFieldLabel__emailAddress_phoneNumber',
+      'formFieldLabel__phoneNumber_username',
+      'formFieldLabel__emailAddress_phoneNumber_username',
+      'formFieldInputPlaceholder__emailAddress_phoneNumber',
+      'formFieldInputPlaceholder__phoneNumber_username',
+      'formFieldInputPlaceholder__emailAddress_phoneNumber_username',
+      'userProfile.phoneNumberPage.infoText__secondary',
+      'userProfile.mfaPhoneCodePage.successMessage',
+      'userProfile.profilePage.fileDropAreaTitle',
+      'userProfile.profilePage.fileDropAreaAction',
+    ];
+    ```
+    
+    If you'd like to automate this, you can use the [lodash omit function](https://lodash.com/docs/#omit) as such:
+    
+    ```js
+    import { omit } from 'lodash-es';
+    
+    const localization = omit(yourOldOject, deletedKeys);
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The values of some keys have been changed on the default [en-US localization object](https://github.com/clerk/javascript/blob/main/packages/localizations/src/en-US.ts). The list below shows you the new defaults (as of writing this guide) which you can either use or overwrite. If you have overridden these values, make sure to double check so you can be sure that your modifications are appropriate.
+    
+    ```js
+    const changedValues = {
+      formFieldLabel__organizationName: 'Name',
+      formFieldLabel__organizationSlug: 'Slug',
+      formFieldInputPlaceholder__emailAddresses: 'example@email.com, example2@email.com',
+      formFieldInputPlaceholder__organizationSlug: 'my-org',
+      signUp: {
+        start: {
+          subtitle: 'Welcome! Please fill in the details to get started.',
+          actionText: 'Already have an account?',
+        },
+        emailCode: {
+          subtitle: 'Enter the verification code sent to your email',
+        },
+        phoneCode: {
+          subtitle: 'Enter the verification code sent to your phone',
+        },
+        continue: {
+          subtitle: 'Please fill in the remaining details to continue.',
+          actionText: 'Already have an account?',
+        },
+      },
+      signIn: {
+        start: {
+          title: 'Sign in to {{applicationName}}',
+          subtitle: 'Welcome back! Please sign in to continue',
+          actionText: 'Don’t have an account?',
+        },
+        password: {
+          subtitle: 'Enter the password associated with your account',
+        },
+        forgotPasswordAlternativeMethods: {
+          label__alternativeMethods: 'Or, sign in with another method',
+        },
+        resetPassword: {
+          title: 'Set new password',
+        },
+        phoneCodeMfa: {
+          subtitle: 'To continue, please enter the verification code sent to your phone',
+        },
+        totpMfa: {
+          subtitle: 'To continue, please enter the verification code generated by your authenticator app',
+        },
+        backupCodeMfa: {
+          subtitle: 'Your backup code is the one you got when setting up two-step authentication.',
+        },
+      },
+      userProfile: {
+        formButtonPrimary__continue: 'Save',
+        start: {
+          headerTitle__account: 'Profile details',
+          profileSection: {
+            primaryButton: 'Edit profile',
+          },
+          emailAddressesSection: {
+            detailsAction__unverified: 'Verify',
+            destructiveAction: 'Remove email',
+          },
+          mfaSection: {
+            phoneCode: {
+              destructiveActionLabel: 'Remove',
+            },
+            backupCodes: {
+              actionLabel__regenerate: 'Regenerate',
+            },
+          },
+          dangerSection: {
+            title: 'Account termination',
+            deleteAccountButton: 'Delete account',
+          },
+        },
+        profilePage: {
+          imageFormSubtitle: 'Upload',
+          imageFormDestructiveActionSubtitle: 'Remove',
+        },
+        phoneNumberPage: {
+          title: 'Add a phone number',
+          infoText:
+            'A text message containing a verification link will be sent to this phone number. Message and data rates may apply.',
+        },
+        connectedAccountPage: {
+          socialButtonsBlockButton: '{{provider|titleize}}',
+        },
+        mfaPhoneCodePage: {
+          subtitle__availablePhoneNumbers:
+            'Select an existing phone number to register for SMS code two-step verification or add a new one.',
+          subtitle__unavailablePhoneNumbers:
+            'There are no available phone numbers to register for SMS code two-step verification, please add a new one.',
+        },
+        deletePage: {
+          actionDescription: 'Type "Delete account" below to continue.',
+        },
+      },
+      organizationSwitcher: {
+        action__createOrganization: 'Create organization',
+        action__manageOrganization: 'Manage',
+      },
+      organizationProfile: {
+        profilePage: {
+          title: 'Update Profile',
+          dangerSection: {
+            title: 'Danger',
+            leaveOrganization: {
+              actionDescription: 'Type "{{organizationName}}" below to continue.',
+            },
+            deleteOrganization: {
+              actionDescription: 'Type "{{organizationName}}" below to continue.',
+            },
+          },
+        },
+        invitePage: {
+          title: 'Invite new members',
+          subtitle: 'Enter or paste one or more email addresses, separated by spaces or commas.',
+        },
+      },
+      createOrganization: {
+        title: 'Create organization',
+      },
+      organizationList: {
+        title: 'Choose an account',
+        titleWithoutPersonal: 'Choose an organization',
+      },
+    };
+    ```
+  </AccordionPanel>
+</Accordion>
+

package/dist/guide-generators/v5/retheme/index.js

@@ -0,0 +1,24 @@
+import { accordionForCategory, assembleContent, frontmatter, loadVersionChangeData, markdown, writeToFile } from '../../text-generation.js';
+const cwd = 'v5/retheme';
+async function generate() {
+  const data = await loadVersionChangeData('v5', 'nextjs');
+  const defaultsChangeItem = {
+    title: 'Changes to default variables',
+    content: `\nThe default values of some [appearance variables](/docs/components/customization/variables) have changed which may impact your UI (if you are not already overriding them).
+
+    - The default \`colorPrimary\` value changed from \`#103FEF\` to \`#2F3037\`. As the new color is a dark grey, the \`colorPrimary\` of the dark theme was changed to \`#FFFFFF\`.
+    - The default \`fontSize\` value changed from \`1rem\` to \`0.8125rem\`
+    - The default \`fontWeight\` values changed from \`{ normal: 400, medium: 500, bold: 600 }\` to \`{ normal: 400, medium: 500, bold: 700 }\`
+    - Previously, the default value for \`fontSmoothing\` was \`auto\`. This value is now unset. If you want to pass a custom value to it, you can still do so.\n`
+  };
+  return assembleContent({
+    data: data,
+    cwd
+  }, [frontmatter({
+    title: 'Redesigned Components in v5',
+    description: 'Learn how to handle changes as a result of redesigned components in Clerk version 5'
+  }), '# Redesigned Components in v5', markdown('intro'), '## Appearance Changes', accordionForCategory('appearance', {
+    additionalItems: defaultsChangeItem
+  }), '## Localization Changes', accordionForCategory('localization')]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/v5/retheme/intro.mdx

@@ -0,0 +1,9 @@
+The new version ships with improved design and UX across all of Clerk's [UI components](/docs/components/overview). If you have used the [`appearance` prop](/docs/components/customization/overview) or tokens for a [custom theme](/docs/components/customization/overview#create-a-custom-theme), you will likely need to make some adjustments to ensure your styling is still looking great. If you're using the [localization prop](/docs/components/customization/localization) you will likely need to make adjustments to account for added or removed localization keys.
+
+<Callout type='info'>
+  If you are not customizing the appearance of your components, or using `localization`, you can skip this section. If
+  you are, we recommend using our CLI (`npx @clerk/upgrade`) to scan for changes required as part of the component
+  redesign more quickly.
+</Callout>
+
+The sections below contain more info on each change made to the customization ids and localization keys for reference. Regardless of how thoroughly you have reviewed the following information, we still recommend that you ensure that you have taken some time to manually look through each of your views to ensure that everything looks good still.

package/dist/guide-generators/v5/shared/after-sign-x-handling.mdx

@@ -0,0 +1,10 @@
+### After sign up/in/out URL handling
+
+Defining redirect URLs for after sign up, in, and/or out via the Clerk dashboard has been removed in Core 2. In your Clerk dashboard, under "paths", there is a section called "Component paths", where URLs could be defined that had a deprecation warning. In Core 2, this functionality has been removed, and specifying redirect paths via the dashboard will no longer work. If you need to pass a redirect URL for after sign in/up/out, there are [a few different ways this can be done](https://clerk.com/docs/account-portal/custom-redirects), from environment variables to middleware to supplying them directly to the relevant components.
+
+As part of this change, the default URL for each of these props has been set to `/`, so if you are passing `/` explicitly to any one of the above props, that line is no longer necessary and can be removed.
+
+```diff
+- <UserButton afterSignOutUrl='/' />
++ <UserButton />
+```

package/dist/guide-generators/v5/shared/cli.mdx

@@ -0,0 +1,22 @@
+## CLI upgrade helper
+
+As of this release cycle, Clerk provides a `@clerk/upgrade` CLI tool that you can use to ease the upgrade. The tool will scan your codebase and produce a list of changes you'll need to apply to your project. It should catch the vast majority of the changes needed for a successful upgrade to Core 2. This can save you a lot of time reading through changes that don't apply to your project.
+
+To run the CLI tool, navigate to your project and run it in the terminal:
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  ```bash filename="terminal"
+  npx @clerk/upgrade
+  ```
+
+```bash filename="terminal"
+yarn dlx @clerk/upgrade
+```
+
+```bash filename="terminal"
+pnpm dlx @clerk/upgrade
+```
+
+</CodeBlockTabs>
+
+If you are having trouble with `npx`, it's also possible to install directly with `npm i @clerk/upgrade -g`, and can then be run with the `clerk-upgrade` command.

package/dist/guide-generators/v5/shared/deprecation-removals.mdx

@@ -0,0 +1,6 @@
+As part of this major version, a number of previously deprecated props, arugments, methods, etc. have been removed. Additionally there have been some changes to things that are only used internally, or only used very rarely. It's highly unlikely that any given app will encounter any of these items, but they are all breaking changes, so they have all been documented below.
+
+<Callout type='info'>
+  For this section more than any other one, please use the CLI upgrade tool (`npx @clerk/upgrade`). Changes in this
+  section are very unlikely to appear in your codebase, the tool will save time looking for them.
+</Callout>

package/dist/guide-generators/v5/shared/hof-removals.mdx

@@ -0,0 +1,3 @@
+### Some higher-order functions and components removed
+
+A set of higher-order functions and components that are easily replicated with userland code and were rarely used have been removed. Each of them are listed below, along with code snippets with which they can be reproduced if need be.

package/dist/guide-generators/v5/shared/image-url.mdx

@@ -0,0 +1,3 @@
+### Image URL Name Consolidation
+
+There are a number of Clerk primitives that contain images, and previously they each had different property names, like `avatarUrl`, `logoUrl`, `profileImageUrl`, etc. In order to promote consistency and make it simpler for developers to know where to find associated images, all image properties are now named `imageUrl`. See the list below for all affected classes:

package/dist/guide-generators/v5/shared/node-setters-removals.mdx

@@ -0,0 +1,34 @@
+### Clerk client setters removed in favor of `createClerkClient` options
+
+The following setter methods have been removed in the lastest version. If you were using any of these functions, their functionality can be replaced by instead passing the correponding option to `createClerkClient`.
+
+- `setClerkApiVersion`
+- `setClerkHttpOptions`
+- `setClerkServerApiUrl`
+- `setClerkApiKey`
+
+Code example:
+
+```diff
+  import {
+     clerkClient,
+-    setClerkApiKey,
+-    setClerkApiVersion,
+-    setClerkHttpOptions,
+-    setClerkServerApiUrl
+} from "@clerk/clerk-sdk-node"
+ 
+- setClerkApiKey("...")
+- setClerkApiVersion("...")
+- setClerkHttpOptions("...")
+- setClerkServerApiUrl("...")
+
+  const clerkClient = createClerkClient({
++     secretKey: "..."
++     apiVersion: "..."
++     httpOptions: "..."
++     serverApiUrl: "..."
+  })
+
+  await clerkClient.users.getUser(userId);
+```

package/dist/guide-generators/v5/shared/node-version.mdx

@@ -0,0 +1,3 @@
+**Updating Node.js**
+
+You need to have Node.js `18.17.0` or later installed. Last year, Node.js 16 entered EOL (End of life) status, so support for this version has been removed across Clerk SDKs. You can check your Node.js version by running `node -v` in your terminal. Learn more about how to [update and install Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs).

package/dist/guide-generators/v5/shared/orgs-claim.mdx

@@ -0,0 +1,50 @@
+### Removed: `orgs` claim on JWT
+
+In the previous version of Clerk's SDKs, if you decode the session token that Clerk returns from the server, you'll currently find an `orgs` claim on it. It lists all the orgs associated with the given user. Now, Clerk returns the `org_id`, `org_slug`, and `org_role` of the **active** organization.
+
+The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where the `JwtPayload` could be found.
+
+<Accordion titles={["Next.js", "Fastify", "@clerk/backend", "@clerk/clerk-sdk-node"]} heading="h5">
+  <AccordionPanel>
+    ```typescript filename="Next.js"
+    import { getAuth } from "@clerk/nextjs/server"
+    const claims: JwtPayload = getAuth(request).sessionClaims
+
+    import { getAuth } from "@clerk/ssr.server"
+    const claims: JwtPayload = (await getAuth(request)).sessionClaims
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    ```typescript filename="Fastify"
+    import { getAuth } from "@clerk/fastify"
+    const claims: JwtPayload = (await getAuth(request)).sessionClaims
+    ```
+  </AccordionPanel>
+  <AccordionPanel>
+    ```typescript filename="@clerk/backend"
+    import { createClerkClient } from "@clerk/backend"
+
+    const clerkClient = createClerkClient({ secretKey: "" })
+    const requestState = await clerkClient.authenticateRequest(
+      request,
+      { publishableKey: "" }
+    )
+    const claims: JwtPayload = requestState.toAuth().sessionClaims
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    ```typescript filename="@clerk/clerk-sdk-node"
+    import { clerkClient } from "@clerk/clerk-sdk-node"
+
+    router.use((...args) => clerkClient.expressRequireAuth()(...args))
+    router.get("/me", async (req, reply: Response) => {
+      return reply.json({ auth: req.auth })
+    })
+    ```
+
+  </AccordionPanel>
+</Accordion>
+
+If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it.

package/dist/guide-generators/v5/shared/pagination-args.mdx

@@ -0,0 +1,3 @@
+### Changes to pagination arguments for some functions
+
+There were some changes made to pagination-related arguments passed into functions, in order to make it more clear how to control paginated results. See each function impacted by these changes below:

package/dist/guide-generators/v5/shared/pagination-return.mdx

@@ -0,0 +1,3 @@
+### Changes to some function return signatures
+
+There have been changes to return signatures for some functions. Since Clerk's API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily. This change also aligns the response shape with what is returned from the Clerk backend API. Each impacted function is listed below, along with code examples: