@clerk/upgrade 0.2.0 → 0.3.0

package/dist/guide-generators/v5/overview/per-sdk.mdx

@@ -0,0 +1,16 @@
+## SDK Guides
+
+Select the SDK(s) you are using for your project from the list below to read through a summary of all the breaking changes:
+
+> Note: I want a prettier selection component here, in it's absence for now there's a list
+
+- [Next.js](upgrading-nextjs-from-v4-to-v5)
+- [Remix](#remix)
+- [Expo](#expo)
+- [Gatsby](#gatsby)
+- [Backend](#backend)
+- [Node](#node)
+- [Fastify](#fastify)
+- [React](#react)
+- [JS](#js)
+- [Chrome Extension](#chrome-extension)

package/dist/guide-generators/v5/per-sdk.mdx

@@ -0,0 +1,16 @@
+## SDK Guides
+
+Select the SDK(s) you are using for your project from the list below to read through a summary of all the breaking changes:
+
+> Note: I want a prettier selection component here, in it's absence for now there's a list
+
+- [Next.js](upgrading-nextjs-from-v4-to-v5)
+- [Remix](#remix)
+- [Expo](#expo)
+- [Gatsby](#gatsby)
+- [Backend](#backend)
+- [Node](#node)
+- [Fastify](#fastify)
+- [React](#react)
+- [JS](#js)
+- [Chrome Extension](#chrome-extension)

package/dist/guide-generators/v5/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.