@clerk/upgrade 0.2.1 → 0.4.0

package/dist/guide-generators/core-2/node/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/core-2/overview/index.js

@@ -0,0 +1,12 @@
+import { assembleContent, frontmatter, markdown, writeToFile } from '../../text-generation.js';
+const cwd = 'core-2/overview';
+async function generate() {
+  return assembleContent({
+    data: {},
+    cwd
+  }, [frontmatter({
+    title: `Upgrading to Clerk Core 2`,
+    description: `Learn how to upgrade to the latest version of Clerk's SDKs`
+  }), markdown('intro')]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/core-2/overview/intro.mdx

@@ -0,0 +1,25 @@
+# Upgrading to Clerk Core 2
+
+In Febrary 2024, [we updated](https://clerk.com/changelog/2024-01-16) Clerk's SDKs to include Core 2. This new core includes:
+
+- 💅 Redesigned and improved component UIs.
+- 🔪 The 401 & "flash of white page" that was visible sometimes when syncing auth state was eliminated.
+- 🧹 A large number of smaller housekeeping changes, bugfixes, and improvements.
+- 📊 [Telemetry](/docs/telemetry) to allow us to better determine feature usage and priority (easy opt-out if you don't like this)
+
+## SDK Guides
+
+Core 2 brings both UI changes and breaking code changes, so each SDK has been updated to a new major version.
+We expect upgrades to take less than 30 minutes, and are providing a CLI tool to assist with the process. Please select your SDK below to get started:
+
+- [Next.js](/nextjs)
+- [Remix](/remix)
+- [Expo](/expo)
+- [Node](/node)
+- [Fastify](/fastify)
+- [React](/react)
+- [Backend](/backend)
+- [JS](/js)
+- [Chrome Extension](/chrome-extension)
+
+Note that the `Gastsby`, `Go`, and `Ruby` SDKs do not yet have a beta release ready - if you are using any of these SDKs there is nothing actionable right now.

package/dist/guide-generators/core-2/react/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/core-2/react/index.js

@@ -0,0 +1,25 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v5';
+const name = 'react';
+const properName = 'React';
+const packageName = '@clerk/clerk-react';
+const cwd = `${version}/${name}`;
+async function generate() {
+  const data = await loadVersionChangeData(version, name);
+  return assembleContent({
+    data,
+    cwd
+  }, [frontmatter({
+    title: `Upgrading ${properName} to Core 2`,
+    description: `Learn how to upgrade Clerk's ${properName} SDK to the latest version.`
+  }), `# Upgrading \`${packageName}\` to Core 2`, markdown('intro'), markdownTemplate('prepare', {
+    packageName,
+    version: semverVersion
+  }), markdown('node-version'), markdown('react-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', markdown('redesign-preview'), markdown('after-sign-x-handling'), singleItem('navigate-to-routerpush-routerreplace'), markdown('orgs-claim'), markdownTemplate('path-routing', {
+    packageName
+  }), markdown('image-url'), accordionForCategory('image-url'), deprecationRemovalsAndHousekeeping(['hof-removal', 'pagination-return', 'pagination-args', 'error-imports'])]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/core-2/react/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the React SDK starting with version 5. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, and a variety of smaller DX improvements and housekeeping items. Each of the potentially breaking changes are detailed in this guide, below.
+
+By the end of this guide, you’ll have successfully upgraded your React project to use `@clerk/clerk-react` v5. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations. Step-by-step instructions will lead you through the process.

package/dist/guide-generators/core-2/remix/index.js

@@ -0,0 +1,25 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v4';
+const name = 'remix';
+const properName = 'Remix';
+const packageName = '@clerk/remix';
+const cwd = `${version}/${name}`;
+async function generate() {
+  const data = await loadVersionChangeData(version, name);
+  return assembleContent({
+    data: data,
+    cwd
+  }, [frontmatter({
+    title: `Upgrading ${properName} to Core 2`,
+    description: `Learn how to upgrade from the Clerk ${properName} SDK to the latest version.`
+  }), `# Upgrading \`${packageName}\` to Core 2`, markdown('intro'), markdownTemplate('prepare', {
+    version: semverVersion,
+    packageName
+  }), markdown('node-version'), markdown('react-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', singleItem('clerkerrorboundary-removed'), markdown('redesign-preview'), markdown('after-sign-x-handling'), markdown('orgs-claim'), markdownTemplate('path-routing', {
+    packageName
+  }), markdown('image-url'), accordionForCategory('image-url'), deprecationRemovalsAndHousekeeping()]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/core-2/remix/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the Remix SDK starting with version 4. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, no more need to add a custom error boundary, and a variety of smaller DX improvements and housekeeping items. Each of the potentially breaking changes are detailed in this guide, below.
+
+By the end of this guide, you’ll have successfully upgraded your Remix project to use `@clerk/remix` v4. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations. Step-by-step instructions will lead you through the process.

package/dist/guide-generators/core-2/retheme/index.js

@@ -0,0 +1,23 @@
+import { accordionForCategory, assembleContent, frontmatter, loadVersionChangeData, markdown, writeToFile } from '../../text-generation.js';
+const cwd = 'core-2/retheme';
+async function generate() {
+  const data = await loadVersionChangeData('core-2', '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, semibold: 600, bold: 700 }\`.\n`
+  };
+  return assembleContent({
+    data: data,
+    cwd
+  }, [frontmatter({
+    title: 'Redesigned Components in Core 2',
+    description: 'Learn how to handle changes as a result of redesigned components in Clerk Core 2'
+  }), '# Redesigned Components in Core 2', markdown('intro'), '## Appearance Changes', accordionForCategory('appearance', {
+    additionalItems: [defaultsChangeItem]
+  }), '## Localization Changes', accordionForCategory('localization')]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/core-2/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/core-2/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/core-2/shared/cli.mdx

@@ -0,0 +1,22 @@
+## CLI upgrade helper
+
+Clerk now provides a `@clerk/upgrade` CLI tool that you can use to ease the upgrade process. 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 any SDK including 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/core-2/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/core-2/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/core-2/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/core-2/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/core-2/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/core-2/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:

package/dist/guide-generators/core-2/shared/path-routing.mdx

@@ -0,0 +1,57 @@
+### Path routing is now the default
+
+On components like [`<SignIn />`](/docs/components/authentication/sign-in) you can define the props `routing` and `path`. `routing` can be set to `'hash' | 'path' | 'virtual'` and describes the routing strategy that should be used. `path` defines where the component is mounted when `routing="path"` is used.
+
+In the latest version, the **default** `routing` strategy has become `'path'`. Unless you change the `routing` prop, you'll need to define the `path` prop. The affected components are:
+
+- `<SignIn />`
+- `<SignUp />`
+- `<UserProfile />`
+- `<CreateOrganization />`
+- `<OrganizationProfile />`
+
+Here's how you'd use the components going forward:
+
+```jsx
+<SignIn path="/sign-in" />
+<SignUp path="/sign-up" />
+<UserProfile path="/user-profile" />
+<CreateOrganization path="/create-org" />
+<OrganizationProfile path="/org-profile" />
+```
+
+If you don't define the `path` prop an error will be thrown. Of course, you can still use `routing="hash"` or `routing="virtual"`.
+
+```jsx
+<UserProfile routing="hash" />
+<OrganizationProfile routing="virtual" />
+```
+
+<% if (['@clerk/nextjs', '@clerk/remix'].includes(packageName)) { %>
+For the <%= packageName %> SDK, you can set environment variables for the sign up/in URLs and avoid needing to explicitly pass the path to the `<SignIn />` and `<SignUp />` components.
+
+<% if (packageName === '@clerk/nextjs') { %>
+
+```env filename=".env.local"
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+```
+
+<% } %>
+<% if (packageName === '@clerk/remix') { %>
+
+```env filename=".env"
+CLERK_SIGN_IN_URL=/sign-in
+CLERK_SIGN_UP_URL=/sign-up
+```
+
+<% } %>
+
+If you have defined both environment variables, you're able to use the `<SignIn />` and `<SignUp />` components without any props, as such:
+
+```jsx
+<SignIn />
+<SignUp />
+```
+
+<% } %>

package/dist/guide-generators/core-2/shared/prepare.mdx

@@ -0,0 +1,10 @@
+## Preparing to upgrade
+
+Before uprading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (`npm i <%= packageName %>@<%= parseInt(version.substring(1)) - 1 %>`). Some changes required for Core 2 SDKs can be applied incrementally to the <%= version %> release, which should contribute to a smoother upgrading experience. After updating, look out for deprecation messages in your terminal and browser console. By resolving these deprecations you'll be able to skip many breaking changes from Core 2.
+
+<Callout>
+  Note that Core 2 is currently in beta, while we field feedback and ensure stability. Deploying beta versions to
+  production is not recommended and should be done at your own risk.
+</Callout>
+
+Additionally, some of the minumum version requirements for some base dependencies have been updated such that versions that are no longer supported or are at end-of-life are no longer guaranteed to work correctly with Clerk.

package/dist/guide-generators/core-2/shared/react-version.mdx

@@ -0,0 +1,20 @@
+**Updating React**
+
+All react-dependent Clerk SDKs now require you to use React 18 or higher. You can update your project by installing the latest version of `react` and `react-dom`.
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+    ```bash filename="terminal"
+    npm install react@latest react-dom@latest
+    ```
+
+    ```bash filename="terminal"
+    yarn add react@latest react-dom@latest
+    ```
+
+    ```bash filename="terminal"
+    pnpm add react@latest react-dom@latest
+    ```
+
+</CodeBlockTabs>
+
+If you are upgrading from React 17 or lower, make sure to [learn about how to upgrade your React version to 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide) as well.

package/dist/guide-generators/core-2/shared/redesign-preview.mdx

@@ -0,0 +1,5 @@
+### Component design adjustments
+
+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.
+
+[More detail on these changes »](component-redesign)

package/dist/guide-generators/core-2/shared/update-version.mdx

@@ -0,0 +1,18 @@
+## Updating to Core 2 Beta
+
+Whenever you feel ready, go ahead and install the latest beta version of any Clerk SDKs you are using. Make sure that you are prepared to patch some breaking changes before your app will work properly, however. The commands below demonstrate how to install the latest beta.
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+    ```bash filename="terminal"
+    npm install <%= packageName %>@beta
+    ```
+
+    ```bash filename="terminal"
+    yarn add <%= packageName %>@beta
+    ```
+
+    ```bash filename="terminal"
+    pnpm add <%= packageName %>@beta
+    ```
+
+</CodeBlockTabs>

package/dist/guide-generators/text-generation.js

@@ -0,0 +1,109 @@
+import ejs from 'ejs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { parseInline } from 'marked';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export async function loadVersionChangeData(version, sdk) {
+  return (await import(`../versions/${version}/index.js`)).default[sdk];
+}
+
+// Small utility for assembling and spacing out content pieces.
+export function assembleContent(options, content) {
+  return content.reduce((output, item) => {
+    output += typeof item === 'function' ? item(options) : item;
+    output += '\n\n';
+    return output;
+  }, '');
+}
+
+// Renders an object into a frontmatter string
+export function frontmatter(obj) {
+  return `---
+${Object.keys(obj).map(k => `${k}: "${obj[k]}"`).join('\n')}
+---`;
+}
+
+// Renders a markdown file, partial-style - will read out of shared if not found in sdk dir
+export const markdown = partial((p, {
+  cwd
+}) => {
+  const defaultPath = path.join(__dirname, cwd, p + '.mdx');
+  const sharedPath = path.join(__dirname, cwd, '../shared', p + '.mdx');
+  return readFileSync(existsSync(defaultPath) ? defaultPath : sharedPath, 'utf8').trim();
+});
+
+// Renders a markdown file with EJS template valyes
+export const markdownTemplate = partial((p, data, {
+  cwd
+}) => {
+  const defaultPath = path.join(__dirname, cwd, p + '.mdx');
+  const sharedPath = path.join(__dirname, cwd, '../shared', p + '.mdx');
+  return ejs.render(readFileSync(existsSync(defaultPath) ? defaultPath : sharedPath, 'utf8').trim(), data);
+});
+
+// Given a single change item, renders it as its own markdown section.
+// Typically used to highlight a specific change item that has a larger
+// impact and/or is likely to affect most users.
+export const singleItem = partial((slug, {
+  data
+}) => {
+  const item = data.find(i => i.slug === slug);
+  return `### ${item.title}
+
+${item.content.trim()}`;
+});
+
+// Given a set of change data and one or more categories, renders each item
+// in the given categories into an accordion.
+// Typically used to present a set of related changes or a longer list of changes
+// that are de-emphasized as they are unlikely to be present for most users.
+export const accordionForCategory = partial((categories, options, {
+  data
+}) => {
+  const items = filterCategories(data, categories);
+  options ||= {};
+  if (options.additionalItems) items.push(...[].concat(options.additionalItems));
+  return `<Accordion titles={[${items.map(i => `"${parseInline(i.title)}"`).join(', ')}]}>
+${items.map(i => `  <AccordionPanel>${indent('\n' + i.content.trim(), 4)}\n  </AccordionPanel>`).join('\n')}
+</Accordion>`;
+});
+
+// The "deprecation removals & housekeeping" section is standard at the bottom of
+// each migration guide, and comprises a set of breaking changes that any given
+// user is very unlikely to run into, so it is de-emphasized to make the upgrade
+// process feel less scary.
+export const deprecationRemovalsAndHousekeeping = partial((includeCategories, opts) => {
+  includeCategories ||= [];
+  const hasDeprecations = filterCategories(opts.data, 'deprecation-removal').length;
+  const hasOtherChanges = filterCategories(opts.data, [undefined, ...includeCategories]).length;
+  const content = ['### Deprecation removals & housekeeping', markdown('deprecation-removals')];
+  if (hasDeprecations) {
+    content.push('#### Deprecation removals');
+    content.push(accordionForCategory('deprecation-removal'));
+  }
+  if (hasOtherChanges) {
+    content.push('#### Other Breaking changes');
+    content.push(accordionForCategory([undefined, ...includeCategories]));
+  }
+  return assembleContent(opts, content);
+});
+
+// writes output to an mdx file
+export const writeToFile = partial((cwd, content) => {
+  writeFileSync(path.join(__dirname, cwd, '__output.mdx'), content);
+});
+function filterCategories(data, categories) {
+  return data.filter(i => [].concat(categories).includes(i.category));
+}
+
+// Small internal utility to ensure proper indentation within the resulting markup.
+function indent(str, numSpaces) {
+  return str.split('\n').map(l => `${' '.repeat(numSpaces)}${l}`).join('\n');
+}
+
+// Partial application utility, enables assembleContent to pass data into every child easily.
+// This is one of the craziest functions I have written in my day 🥹
+function partial(fn) {
+  return (...args) => fn.bind(null, ...args.concat(Array(fn.length - args.length - 1)));
+}

package/dist/util/load-change.js

@@ -11,8 +11,8 @@ export default function createLoader({
     // Note: This could benefit perf-wise by being converted to async, but it would
     // make the code a decent amount more complex.
     return slugs.map(slug => {
-      const sdkPath = path.join(__dirname, '../versions', `v${version}`, sdk, `${slug}.md`);
-      const sharedPath = path.join(__dirname, '../versions', `v${version}`, 'common', `${slug}.md`);
+      const sdkPath = path.join(__dirname, '../versions', `${version}`, sdk, `${slug}.md`);
+      const sharedPath = path.join(__dirname, '../versions', `${version}`, 'common', `${slug}.md`);
       const loadPath = fs.existsSync(sdkPath) ? sdkPath : sharedPath;
       const content = fs.readFileSync(loadPath, 'utf8');
       const parsed = matter(content);
@@ -25,6 +25,7 @@ export default function createLoader({
         sdk: sdk,
         content: parsed.content,
         warning: fm.warning,
+        category: fm.category,
         link: `${baseUrl}#${slug}`
       };
     });

package/dist/versions/{v5 → core-2}/backend/authenticaterequest-params-change.md

@@ -1,6 +1,7 @@
 ---
 title: '`request` separated from `options` as params to `authenticateRequest`'
 warning: true
+category: 'skip'
 matcher: "authenticateRequest\\("
 ---
 

package/dist/versions/{v5 → core-2}/backend/clockskewinseconds.md

@@ -5,6 +5,7 @@ matcher:
   - "verifyToken\\([\\s\\S]*?(clockSkewInSeconds):[\\s\\S]*?\\)"
   - "authenticateRequest\\([\\s\\S]*?(clockSkewInSeconds):[\\s\\S]*?\\)"
 matcherFlags: 'm'
+category: 'skip'
 replaceWithString: 'clockSkewInMs'
 ---
 

package/dist/versions/{v5 → core-2}/backend/constants-import-path-move.md

@@ -3,6 +3,7 @@ title: '`constants` import moved to `@clerk/backend/internal`'
 matcher: "import\\s+{[\\s\\S]*?constants[\\s\\S]*?}\\s+from\\s+['\"]@clerk\\/(backend)['\"]"
 matcherFlags: 'm'
 replaceWithString: 'backend/internal'
+category: 'import-paths'
 ---
 
 The `constants` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:

package/dist/versions/{v5 → core-2}/backend/createauthenticaterequest-import-path-move.md

@@ -3,6 +3,7 @@ title: '`createAuthenticateRequest` import moved to `@clerk/backend/internal`'
 matcher: "import\\s+{[\\s\\S]*?createAuthenticateRequest[\\s\\S]*?}\\s+from\\s+['\"]@clerk\\/(backend)['\"]"
 matcherFlags: 'm'
 replaceWithString: 'backend/internal'
+category: 'import-paths'
 ---
 
 The `createAuthenticateRequest` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:

package/dist/versions/{v5 → core-2}/backend/createclerkclient-apikey.md

@@ -1,6 +1,7 @@
 ---
 title: '`apiKey` -> `secretKey` as param to createClerkClient'
 matcher: "(?:createClerkClient|Clerk)\\(\\s*{[\\s\\S]*?frontendApi:[\\s\\S]*?\\)"
+category: 'deprecation-removal'
 matcherFlags: 'm'
 ---
 

package/dist/versions/{v5 → core-2}/backend/createclerkclient-frontendapi.md

@@ -2,6 +2,7 @@
 title: '`frontendApi` -> `publishableKey` as param to createClerkClient'
 matcher: "(?:createClerkClient|Clerk)\\(\\s*{[\\s\\S]*?frontendApi:[\\s\\S]*?\\)"
 matcherFlags: 'm'
+category: 'deprecation-removal'
 ---
 
 The `frontendApi` argument passed to `createClerkClient` must be changed to `publishableKey`. Note that the values of the two keys are different, so both keys and values need to be changed. You can find your application's publishable key in the Clerk dashboard. Also note that the import value has changed for creating a new Clerk client, which will be addressed by a separate line item if relevant to your codebase.

package/dist/versions/{v5 → core-2}/backend/createisomorphicrequest-import-path-move.md

@@ -3,6 +3,7 @@ title: '`createIsomorphicRequest` import moved to `@clerk/backend/internal`'
 matcher: "import\\s+{[\\s\\S]*?createIsomorphicRequest[\\s\\S]*?}\\s+from\\s+['\"]@clerk\\/(backend)['\"]"
 matcherFlags: 'm'
 replaceWithString: 'backend/internal'
+category: 'import-paths'
 ---
 
 The `createIsomorphicRequest` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:

package/dist/versions/{v5 → core-2}/backend/createisomorphicrequest-removed.md

@@ -3,6 +3,7 @@ title: '`createIsomorphicRequest` import moved to `/internal`'
 matcher: "import\\s+{[\\s\\S]*?createIsomorphicRequest[\\s\\S]*?}\\s+from\\s+['\"]@clerk\/(backend)['\"]"
 replaceWithString: 'backend/internal'
 matcherFlags: 'm'
+category: 'import-paths'
 ---
 
 The `createIsomorphicRequest` import was intended for those building custom Clerk integrations for frameworks and has been moved to `@clerk/backend/internal` to reflect this. Please use caution when using internal imports as they are outside the bounds of semver.

package/dist/versions/{v5 → core-2}/backend/decodejwt-import-path-move.md

@@ -3,6 +3,7 @@ title: '`decodeJwt` import moved to `@clerk/backend/tokens`'
 matcher: "import\\s+{[\\s\\S]*?decodeJwt[\\s\\S]*?}\\s+from\\s+['\"]@clerk\\/(backend)['\"]"
 matcherFlags: 'm'
 replaceWithString: 'backend/tokens'
+category: 'import-paths'
 ---
 
 The `decodeJwt` import path has changed from `@clerk/backend` to `@clerk/backend/tokens`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made

package/dist/versions/{v5 → core-2}/backend/getorganizationmembershiplist-return-signature.md

@@ -1,6 +1,7 @@
 ---
 title: '`Users.getOrganizationMembershipList` return signature changed'
 matcher: "\\.users\\.getOrganizationMembershipList\\("
+category: 'pagination-return'
 warning: true
 ---