@clerk/upgrade 0.2.0 → 0.3.0

package/dist/util/v5-guide/prepare.mdx

@@ -0,0 +1,135 @@
+## Preparing to upgrade
+
+Before uprading, it's highly recommended that you update your Clerk SDKs to the latest v4 version. Some changes required for v5 can be applied incrementally to the latest v4, 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 for v5.
+
+Additionally, some of the minumum version requirements for Node.js, React, and Next.js 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. Please take a moment to check your dependencies and ensure you are up to date!
+
+#### 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 it's time to bump the required version for `@clerk/nextjs`, too. 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).
+
+#### Updating React
+
+All react-dependent 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.
+
+## Updating to v5
+
+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. Some examples for how to unstall commonly used SDKs are below:
+
+<Tabs type="v4-to-v5-sdk" items={["Next.js", "React", "Remix", "JavaScript", "Node.js"]}>
+  <Tab>
+    <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+      ```bash filename="terminal"
+      npm install @clerk/nextjs@beta
+      ```
+
+      ```bash filename="terminal"
+      yarn add @clerk/nextjs@beta
+      ```
+
+      ```bash filename="terminal"
+      pnpm add @clerk/nextjs@beta
+      ```
+    </CodeBlockTabs>
+  </Tab>
+  <Tab>
+    <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+      ```bash filename="terminal"
+      npm install @clerk/clerk-react@beta
+      ```
+
+      ```bash filename="terminal"
+      yarn add @clerk/clerk-react@beta
+      ```
+
+      ```bash filename="terminal"
+      pnpm add @clerk/clerk-react@beta
+      ```
+    </CodeBlockTabs>
+  </Tab>
+  <Tab>
+    <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+      ```bash filename="terminal"
+      npm install @clerk/remix@beta
+      ```
+
+      ```bash filename="terminal"
+      yarn add @clerk/remix@beta
+      ```
+
+      ```bash filename="terminal"
+      pnpm add @clerk/remix@beta
+      ```
+    </CodeBlockTabs>
+  </Tab>
+  <Tab>
+    <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+      ```bash filename="terminal"
+      npm install @clerk/clerk-js@beta
+      ```
+
+      ```bash filename="terminal"
+      yarn add @clerk/clerk-js@beta
+      ```
+
+      ```bash filename="terminal"
+      pnpm add @clerk/clerk-js@beta
+      ```
+    </CodeBlockTabs>
+  </Tab>
+  <Tab>
+    <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+      ```bash filename="terminal"
+      npm install @clerk/clerk-sdk-node@beta
+      ```
+
+      ```bash filename="terminal"
+      yarn add @clerk/clerk-sdk-node@beta
+      ```
+
+      ```bash filename="terminal"
+      pnpm add @clerk/clerk-sdk-node@beta
+      ```
+    </CodeBlockTabs>
+  </Tab>
+</Tabs>
+
+## CLI Upgrade Helper
+
+As of this major version Clerk provides a `@clerk/upgrade` CLI tool that you can use to ease the upgrade. A CLI prompt will ask you a couple of questions, it will scan your codebase, and afterwards you'll get a list of changes you'll need to apply to your project, as well as the locations where they need to be applied. This should catch the vast majority of the changes needed for a successful upgrade to v5, and can save a lot of time reading through changes to things that aren't actually in 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/util/v5-guide/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 »](#redesigned-components)

package/dist/util/v5-guide/redesigned-components.mdx

@@ -0,0 +1,11 @@
+## Redesigned components
+
+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/util/v5-guides/deprecation-removals.mdx

@@ -0,0 +1,7 @@
+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`). There
+  are a lot of changes, each of which are very unlikely to appear in your codebase, that would take a very long time to
+  look for manually.
+</Callout>

package/dist/util/v5-guides/generate.js

@@ -0,0 +1,200 @@
+import { renderAccordionForCategory, renderFrontmatter, renderMarkdown, renderSingleItem } from '../text-generation.js';
+async function generate() {
+  const data = (await import(`../../versions/v5/index.js`)).default;
+  let output = '';
+  output += renderFrontmatter({
+    title: 'Upgrading from v4 to v5',
+    description: 'Learn how to upgrade from version 4 to version 5 of the Clerk JavaScript libraries.'
+  });
+  output += '\n\n';
+  output += renderMarkdown('v5-guide/intro');
+  output += '\n\n';
+  output += renderMarkdown('v5-guide/prepare');
+  output += '\n\n';
+  output += renderMarkdown('v5-guide/per-sdk');
+  output += '\n\n';
+
+  // ------------------------------------------------------------
+
+  output += '### Remix';
+  output += '\n\n';
+
+  // Error boundary removal
+  output += renderSingleItem('clerkerrorboundary-removed', data.remix);
+  output += '\n\n';
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.remix);
+
+  // ------------------------------------------------------------
+
+  // TODO: I'm not sure we're actually releasing the gatsby changes in v5, should double check this
+  output += '### Gatsby';
+  output += '\n\n';
+
+  // withServerAuth type change
+  output += renderSingleItem('withserverauth-return-type', data.gatsby);
+  output += '\n\n';
+
+  // error import path changes
+  // TODO: need to figure out how widely this applies ⚠️
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.gatsby);
+
+  // ------------------------------------------------------------
+
+  output += '### Expo';
+  output += '\n\n';
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.expo);
+
+  // ------------------------------------------------------------
+
+  output += '### Fastify';
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.fastify);
+
+  // ------------------------------------------------------------
+
+  output += '### Node';
+  output += '\n\n';
+
+  // TODO: plans to deprecate this package in favor of backend/express - maybe?
+
+  // cjs/esm imports
+  output += renderSingleItem('cjs-esm-instance', data.node);
+  output += '\n\n';
+
+  // createClerkClient options instead of setter methods
+  output += renderMarkdown('v5-guide/node-setters-removals');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.node);
+
+  // ------------------------------------------------------------
+
+  output += '### React';
+  output += '\n\n';
+
+  // path routing (TODO: this should be linked to from other react SDKs)
+  output += renderMarkdown('v5-guide/path-routing');
+  output += '\n\n';
+
+  // routerPush/routerReplace
+  output += renderSingleItem('navigate-to-routerpush-routerreplace', data.react);
+  output += '\n\n';
+
+  // useOrganizationsList
+  output += renderSingleItem('useorganizations', data.react);
+  output += '\n\n';
+
+  // HOF removals (TODO: this applies to all react sdks, should be shared section)
+  output += renderMarkdown('v5-guide/hof-removals');
+  output += '\n\n';
+  output += renderAccordionForCategory(data.react, 'hof-removal');
+  output += '\n\n';
+
+  // error import paths
+  // TODO: applies to all sdks, make a shared section
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.react);
+
+  // ------------------------------------------------------------
+
+  output += '### Javascript';
+  output += '\n\n';
+
+  // pagination params
+  output += renderMarkdown('v5-guide/pagination-args');
+  output += '\n\n';
+  output += renderAccordionForCategory(data.js, 'pagination-args');
+  output += '\n\n';
+
+  // data/totalCount return values
+  output += renderMarkdown('v5-guide/pagination-return');
+  output += '\n\n';
+  output += renderAccordionForCategory(data.js, 'pagination-return');
+  output += '\n\n';
+
+  // ------------------------------------------------------------
+
+  output += '### Backend';
+  output += '\n\n';
+
+  // ------------------------------------------------------------
+
+  output += '### Chrome Extension';
+  output += '\n\n';
+
+  // ------------------------------------------------------------
+
+  // Component redesign, shared section
+  output += renderMarkdown('v5-guide/redesigned-components');
+  output += '\n\n';
+
+  // This is a guide-specific item, no matcher for this
+  // TODO: add a way to have this be a normal change item but not run in the CLI
+  const defaultsChangeItem = {
+    title: 'Changes to default variables',
+    content: `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.`
+  };
+  output += '#### Appearance changes';
+  output += '\n\n';
+  output += renderAccordionForCategory(data.nextjs, 'appearance', {
+    additionalItems: [defaultsChangeItem]
+  });
+  output += '\n\n';
+  output += '#### Localization changes';
+  output += '\n\n';
+  output += renderAccordionForCategory(data.nextjs, 'localization');
+  output += '\n\n';
+  return output;
+}
+generate().then(console.log);
+
+// This is used the same way for all SDKs, so this fn prevents tons of repetition
+function renderDeprecationRemovalsAndHousekeeping(data) {
+  let output = '';
+  output += '## Deprecation removals & housekeeping';
+  output += '\n\n';
+  output += renderMarkdown('v5-guide/deprecation-removals');
+  output += '\n\n';
+  output += '### Deprecation removals';
+  output += '\n\n';
+  output += renderMarkdown('v5-guide/deprecation-removals');
+  output += '\n\n';
+  output += renderAccordionForCategory(data, 'deprecation-removal');
+  output += '\n\n';
+  output += '### Other Breaking Changes';
+  output += '\n\n';
+  output += renderAccordionForCategory(data, [undefined, 'hof-removal', 'pagination-return', 'pagination-args', 'error-imports']);
+  output += '\n\n';
+  return output;
+}

package/dist/util/v5-guides/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/util/v5-guides/intro.mdx

@@ -0,0 +1,15 @@
+# Upgrading from v4 to v5
+
+Clerk's SDKs include React, Next.js, Remix, Expo, Redwood, and others. This guide helps you with uprading to the next major version of your SDK.
+
+Version 5 ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, and a new middleware for Next.js which defaults to not protecting any routes. Along with these highly requested features some smaller DX improvements and housekeeping items made its way into the release. If you want to know everything that's new, read the [v5 announcement post](https://clerk.com/changelog/2024-01-16).
+
+<Callout type="info" >
+  Version 5/v5 refers to the [`@clerk/clerk-js`](https://www.npmjs.com/package/@clerk/clerk-js) package version. However, other SDKs like `@clerk/backend` or `@clerk/clerk-expo` are versioned independently (and would upgrade from v1 to v2). To make this page easier to read for instances of general advice only v5 is mentioned. You can think of v4 as the previous major of your SDK and v5 as the current in those cases.
+</Callout>
+
+If you're curious about Clerk's approach to versioning and support, head to the [long term support](/docs/upgrade-guides/long-term-support) document. Version 5 includes [potentially breaking changes](#breaking-changes), as well as the removal of [previously deprecated features](#previously-deprecated-features).
+
+For most users we expect a smooth upgrade path as only a couple of changes will be required: [Update dependencies](#update-dependencies), run the `@clerk/upgrade` CLI, [update Clerk](#update-clerk), and handle any [breaking changes](#breaking-changes).
+
+If you're using **Next.js**, you can read a more streamlined [Upgrading Next.js from v4 to v5](/docs/upgrade-guides/upgrading-nextjs-from-v4-to-v5) guide.

package/dist/util/v5-guides/nextjs/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 v5. In your Clerk dashboard, under "paths", there is a section called "Component paths", where URLs could be defined that had a deprecation warning. In v5, 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/util/v5-guides/nextjs/deprecation-removals.mdx

@@ -0,0 +1,9 @@
+## Deprecation removals & housekeeping
+
+As part of this major version, a large 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`). There
+  are a lot of changes, each of which are very unlikely to appear in your codebase, that would take a very long time to
+  look for manually.
+</Callout>

package/dist/util/v5-guides/nextjs/generate.js

@@ -0,0 +1,80 @@
+import { readFileSync } from 'fs';
+import { parseInline } from 'marked';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = 'v5';
+async function generate() {
+  const data = (await import(`../../versions/${VERSION}/index.js`)).default['nextjs'];
+  let output = '';
+  output += `---
+title: Upgrading Next.js from v4 to v5
+description: Learn how to upgrade Clerk's Next.js SDK from v4 to v5.
+---`;
+  output += '\n\n';
+  output += read('intro');
+  output += '\n';
+  output += read('version-requirements');
+
+  // This is a guide-specific item, no matcher for this
+  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`
+  };
+  output += '\n';
+  output += read('retheme-changes');
+  const apperanceChanges = data.filter(i => i.category === 'appearance');
+  apperanceChanges.push(defaultsChangeItem);
+  const localizationChanges = data.filter(i => i.category === 'localization');
+  output += '\n';
+  output += '### Appearance changes';
+  output += '\n\n';
+  output += `<Accordion titles={[${apperanceChanges.map(i => `"${parseInline(i.title)}"`).join(', ')}]}>`;
+  output += '\n';
+  output += apperanceChanges.map(i => `<AccordionPanel>${i.content}</AccordionPanel>`).join('\n');
+  output += '</Accordion>';
+  output += '\n\n';
+  output += '### Localization changes';
+  output += '\n\n';
+  output += `<Accordion titles={[${localizationChanges.map(i => `"${parseInline(i.title)}"`).join(', ')}]}>`;
+  output += '\n';
+  output += localizationChanges.map(i => `<AccordionPanel>${i.content}</AccordionPanel>`).join('\n');
+  output += '</Accordion>';
+  output += '\n\n';
+  output += read('middleware-changes');
+  output += '\n\n';
+  output += read('import-changes');
+  output += '\n';
+  output += read('after-sign-x-handling');
+  output += '\n';
+  output += read('deprecation-removals');
+  const deprecationRemovals = data.filter(i => i.category === 'deprecation-removal');
+  const otherChanges = data.filter(i => !i.category);
+  output += '### Deprecation removals';
+  output += '\n\n';
+  output += `<Accordion titles={[${deprecationRemovals.map(i => `"${parseInline(i.title)}"`).join(', ')}]}>`;
+  output += '\n';
+  output += deprecationRemovals.map(i => `<AccordionPanel>${i.content}</AccordionPanel>`).join('\n');
+  output += '</Accordion>';
+  output += '\n\n';
+  output += '### Other breaking changes';
+  output += '\n\n';
+  output += `<Accordion titles={[${otherChanges.map(i => `"${parseInline(i.title)}"`).join(', ')}]}>`;
+  output += '\n';
+  output += otherChanges.map(i => `<AccordionPanel>${i.content}</AccordionPanel>`).join('\n');
+  output += '</Accordion>';
+  output += '\n\n';
+
+  // TODO: deal with HOF removals
+
+  return output;
+}
+generate().then(console.log);
+function read(p) {
+  return readFileSync(path.join(__dirname, p + '.mdx'), 'utf8');
+}

package/dist/util/v5-guides/nextjs/import-changes.mdx

@@ -0,0 +1,98 @@
+## Changes to top-level exports
+
+As part of this release, some of the top-level exports of `@clerk/nextjs` have been changed in order to improve bundle size and tree-shaking efficiency. These changes have resulted in a ~75% reduction in build size for middleware bundles. However, you will likely need to make some changes to import paths as a result.
+
+<Callout type='info'>
+  Use the CLI tool, `npx @clerk/upgrade`, to automatically find occurences of old imports.
+</Callout>
+
+<Accordion titles={["@clerk/nextjs/server", "@clerk/nextjs/errors", "@clerk/nextjs/app-beta", "@clerk/nextjs/ssr", "@clerk/nextjs/edge-middleware", "@clerk/nextjs/edge-middlewarefiles", "@clerk/nextjs/api"]} heading="h4">
+  <AccordionPanel>
+    Previously these exports have been exported both from `@clerk/nextjs` and `@clerk/nextjs/server`. As of v5 they are only exported from the latter.
+
+    ```diff
+      import {
+        auth,
+        currentUser,
+        authMiddleware,
+        buildClerkProps,
+        verifyToken,
+        verifyJwt,
+        decodeJwt,
+        signJwt,
+        constants,
+        redirect,
+        createAuthenticateRequest,
+        createIsomorphicRequest,
+    - } from "@clerk/nextjs"
+    + } from "@clerk/nextjs/server"
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    Exports related to errors are now under `@clerk/nextjs/errors`.
+
+    ```diff
+      import {
+        isClerkAPIResponseError,
+        isEmailLinkError,
+        isKnownError,
+        isMetamaskError,
+        EmailLinkErrorCode,
+    - } from "@clerk/nextjs"
+    + } from "@clerk/nextjs/errors"
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    The `@clerk/nextjs` import will work with both the app and pages router.
+
+    ```diff
+    - import { } from "@clerk/nextjs/app-beta"
+    + import { } from "@clerk/nextjs"
+    ```
+
+    Some behavior may have changed between Clerk's beta and the stable release. Please check on your end if behavior stayed the same.
+
+  </AccordionPanel>
+  <AccordionPanel>
+    The top-level exports support SSR by default now.
+
+    ```diff
+    - import { } from "@clerk/nextjs/ssr"
+    + import { } from "@clerk/nextjs"
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    ```diff
+    - import { } from "@clerk/nextjs/edge-middleware"
+    + import { } from "@clerk/nextjs"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>
+    ```diff
+    - import { } from "@clerk/nextjs/edge-middlewarefiles"
+    + import { } from "@clerk/nextjs"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>
+    The `@clerk/nextjs/api` subpath was removed completely. It re-exported helpers from `@clerk/clerk-sdk-node` and its types. If you relied on these, import from `@clerk/clerk-sdk-node` directly instead.
+
+    ```diff
+      import type {
+        ClerkMiddleware,
+        ClerkMiddlewareOptions,
+        LooseAuthProp,
+        RequireAuthProp,
+        StrictAuthProp,
+        WithAuthProp
+    - } from "@clerk/nextjs/api"
+    + } from "@clerk/clerk-sdk-node"
+
+    - import { requireAuth, withAuth } from "@clerk/nextjs/api"
+    + import { requireAuth, withAuth } from "@clerk/clerk-sdk-node"
+    ```
+
+  </AccordionPanel>
+</Accordion>

package/dist/util/v5-guides/nextjs/intro.mdx

@@ -0,0 +1,21 @@
+# Upgrading Next.js from v4 to v5
+
+By the end of this guide, you’ll have successfully upgraded your Next.js project to use `@clerk/nextjs` 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. If you’re looking for a reference list of changes, check out the general [upgrading from v4 to v5 guide](/docs/upgrade-guides/upgrading-from-v4-to-v5).
+
+To aid you in this upgrade, Clerk built a CLI called [`@clerk/upgrade`](https://www.npmjs.com/package/@clerk/upgrade). Throughout this guide you'll see prompts to use the CLI which you can invoke directly in your 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>