@clerk/upgrade 0.2.1 → 0.4.0

package/dist/constants/sdks.js

@@ -4,10 +4,9 @@ export default [{
 }, {
   label: '@clerk/remix',
   value: 'remix'
-}, {
-  label: 'gatsby-plugin-clerk',
-  value: 'gatsby'
-}, {
+},
+// { label: 'gatsby-plugin-clerk', value: 'gatsby' },
+{
   label: '@clerk/redwood',
   value: 'redwood'
 }, {
@@ -42,5 +41,5 @@ export default [{
   value: 'types'
 }, {
   label: '@clerk/chrome-extension',
-  value: 'chromeExtension'
+  value: 'chrome-extension'
 }];

package/dist/guide-generators/core-2/backend/import-paths.mdx

@@ -0,0 +1,3 @@
+### Import paths changes
+
+Some top level import paths have been changed in order to improve tree-shaking and more clearly categorize sets of functionality. Some methods have been moved under an `/internal` path, indicating that they are only intended for internal use, are exempt from semver, and should be used with great caution.

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

@@ -0,0 +1,22 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const name = 'backend';
+const properName = 'Backend';
+const packageName = '@clerk/backend';
+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', {
+    version: 'v1',
+    packageName
+  }), markdown('node-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', singleItem('authenticaterequest-params-change'), singleItem('clockskewinseconds'), markdown('import-paths'), accordionForCategory('import-paths'), singleItem('httpoptions-removed'), markdown('orgs-claim'), markdown('pagination-args'), accordionForCategory('pagination-args'), markdown('pagination-return'), accordionForCategory('pagination-return'), markdown('image-url'), accordionForCategory(['image-url', 'image-url-backend']), deprecationRemovalsAndHousekeeping()]);
+}
+generate().then(writeToFile(cwd));

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

@@ -0,0 +1,3 @@
+Core 2 is included in the Backend SDK starting with version 1. This new version ships with 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 Backend project to use `@clerk/backend` v1. 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/chrome-extension/index.js

@@ -0,0 +1,24 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const name = 'chrome-extension';
+const properName = 'Chrome Extension';
+const packageName = '@clerk/chrome-extension';
+const cwd = `${version}/${name}`;
+async function generate() {
+  const data = await loadVersionChangeData(version, name);
+  return assembleContent({
+    data,
+    cwd
+  }, [frontmatter({
+    title: `Upgrading ${properName} SDK 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', {
+    version: 'v1',
+    packageName
+  }), markdown('node-version'), markdown('react-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', singleItem('clerkprovider-tokencache'), markdown('redesign-preview'), markdown('after-sign-x-handling'), 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/chrome-extension/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the Chrome Extension SDK starting with version 1. 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 project to use `@clerk/chrome-extension` v1. 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/expo/index.js

@@ -0,0 +1,25 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v1';
+const name = 'expo';
+const properName = 'Expo';
+const packageName = '@clerk/clerk-expo';
+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', {
+    version: semverVersion,
+    packageName
+  }), markdown('node-version'), markdown('react-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', markdown('redesign-preview'), markdown('after-sign-x-handling'), 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/expo/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the Expo SDK starting with version 1. This release ships with an improved design and UX for its built-in components 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 Expo project to use `@clerk/clerk-expo` v1. 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/fastify/index.js

@@ -0,0 +1,23 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v1';
+const name = 'fastify';
+const properName = 'Fastify';
+const packageName = '@clerk/fastify';
+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', {
+    version: semverVersion,
+    packageName
+  }), markdown('node-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', markdown('orgs-claim'), 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/fastify/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the Fastify SDK starting with version 1. This release ships with 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 Fastify project to use `@clerk/fastify` 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/gatsby/index.js

@@ -0,0 +1,25 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v5';
+const name = 'gatsby';
+const properName = 'Gatsby';
+const packageName = 'gatsby-plugin-clerk';
+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', {
+    version: semverVersion,
+    packageName
+  }), markdown('node-version'), markdown('react-version'), markdownTemplate('update-version', {
+    packageName: 'gatsby-plugin-clerk'
+  }), markdown('cli'), '## Breaking Changes', 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/gatsby/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the Gatsby 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 Gatsby project to use `gatsby-plugin-clerk` 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/generate-all.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+node $SCRIPT_DIR/overview/index.js
+node $SCRIPT_DIR/backend/index.js
+node $SCRIPT_DIR/chrome-extension/index.js
+node $SCRIPT_DIR/expo/index.js
+node $SCRIPT_DIR/fastify/index.js
+node $SCRIPT_DIR/gatsby/index.js
+node $SCRIPT_DIR/js/index.js
+node $SCRIPT_DIR/nextjs/index.js
+node $SCRIPT_DIR/node/index.js
+node $SCRIPT_DIR/react/index.js
+node $SCRIPT_DIR/remix/index.js
+node $SCRIPT_DIR/retheme/index.js

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

@@ -0,0 +1,28 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v5';
+const name = 'js';
+const properName = 'Javascript';
+const packageName = '@clerk/clerk-js';
+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', {
+    version: semverVersion,
+    packageName
+  }), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', markdown('redesign-preview'), markdown('after-sign-x-handling'), markdown('orgs-claim'), markdownTemplate('path-routing', {
+    packageName
+  }), markdown('image-url'), accordionForCategory('image-url'), markdown('pagination-args'), accordionForCategory('pagination-args'), markdown('pagination-return'), accordionForCategory('pagination-return'),
+  // createOrganization args?
+  // attemptweb3wallet?
+  deprecationRemovalsAndHousekeeping(['error-imports'])]);
+}
+generate().then(writeToFile(cwd));

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

@@ -0,0 +1,3 @@
+Core 2 is included in the Javascript 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 JS project to use `@clerk/clerk-js` 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/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](#cli-upgrade-helper) to automatically find occurences of imports that need to be changed.
+</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"]}>
+  <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. Going forward, the expectation can be that any imports that are intended to run within react on the client side, will come from `@clerk/nextjs` and imports that are intended to run on the server, will come from `@clerk/nextjs/server`.
+
+    ```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/guide-generators/core-2/nextjs/index.js

@@ -0,0 +1,25 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v5';
+const name = 'nextjs';
+const properName = 'Next.js';
+const packageName = '@clerk/nextjs';
+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', {
+    version: semverVersion,
+    packageName
+  }), markdown('node-version'), markdown('react-version'), markdown('nextjs-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', markdown('redesign-preview'), markdown('middleware-changes'), markdown('import-changes'), markdown('after-sign-x-handling'), 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/nextjs/intro.mdx

@@ -0,0 +1,3 @@
+Core 2 is included in the Next.js SDK starting with version 5.0.0. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, a substantially improved middleware import, 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 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.

package/dist/guide-generators/core-2/nextjs/middleware-changes.mdx

@@ -0,0 +1,229 @@
+### New Middleware architecture
+
+User and customer feedback about `authMiddleware()` has been clear in that Middleware logic was a often friction point. As such, in v5 you will find a completely new Middleware helper called [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware) that should alleviate the issues folks had with `authMiddleware()`.
+
+Additionally, there are now new helpers that enable controlling auth on a _per-page and/or per-layout basis_ when using App Router. While you can still configure which routes are protected via Middleware, the page-based protection strategy is what is now recommended, as the co-location of auth protection configuration with the code for the pages themselves results in a superior developer experience that adds clarity as you navigate your codebase.
+
+#### Per-route auth config
+
+Sometimes, code speaks louder than words. Let's get right into an example:
+
+<Tabs type="auth-protect-layout-page" items={["Layout", "Page"]}>
+  <Tab>
+    ```ts filename="app/src/dashboard/layout.tsx"
+    import { auth } from '@clerk/nextjs/server'
+
+    export default async function DashboardLayout({ children }) {
+        auth().protect();
+        // 👆 This one line is all it takes - the layout and all its children
+        // will now redirect to your sign in page for un-authenticated users.
+
+        return <>{children}</>
+    }
+    ```
+
+  </Tab>
+  <Tab>
+    ```ts filename="app/src/dashboard/page.tsx"
+    import { auth } from '@clerk/nextjs/server'
+
+    export default async function DashboardPage() {
+        auth().protect();
+        // 👆 This one line is all it takes - the layout and all its children
+        // will now redirect to your sign in page for un-authenticated users.
+
+        return <p>This page is now protected!</p>
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+In this example, you add [`auth().protect()`](/docs/references/nextjs/auth#protect) to a layout and that layout and all of it's children will be gated by auth. The same logic can be applied for pages.
+
+For more details on route protection, check out the [route protection guide](/references/nextjs/route-protection).
+
+If you are using the pages router, per-route gating won't work. Instead, configure your auth gating via Middleware as described in the next section.
+
+#### Middleware auth config
+
+If you prefer to define your auth logic within the Middleware, you can still do this using the new `clerkMiddleware`. The primary change from the previous `authMiddleware()` is that `clerkMiddleware()` does not protect any routes by default, instead requiring the developer to add routes they would like to be protected by auth. This is a substantial contrast to the previous `authMiddleware()`, which protected all routes by default, requiring the developer to add exceptions. The API was also substantially simplified, and it has become easier to combine with other Middleware helpers smoothly as well.
+
+Here's an example that replicates the auth protection scheme above, but entirely inside the Middleware:
+
+```ts filename="middleware.ts"
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isDashboardRoute = createRouteMatcher(['/dashboard(.*)']);
+const isAdminRoute = createRouteMatcher(['/admin(.*)']);
+
+export default clerkMiddleware((auth, req) => {
+  // Restrict admin route to users with specific role
+  if (isAdminRoute(req)) auth().protect({ role: 'org:admin' });
+
+  // Restrict dashboard routes to logged in users
+  if (isDashboardRoute(req)) auth().protect();
+});
+
+export const config = {
+  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)'],
+};
+```
+
+A couple things to note here:
+
+- The `createRouteMatcher` helper makes it easy to define route groups that you can leverage inside the Middleware function and check in whichever order you'd like. Note that it can take an array of routes as well.
+- With `clerkMiddleware`, you're defining the routes you want **to be protected**, rather than the routes you don't want to be protected.
+- You are able to use the same `auth().protect()` helpers that you can use within layouts/pages here in the Middleware.
+
+#### Migrating to `clerkMiddleware()`
+
+Clerk strongly recommends migrating to the new `clerkMiddleware()` for an improved DX and access to all present and upcoming features, but also want to note that `authMiddleware()`, while deprecated, will continue to work in v5 and will not be removed until the next major version, so you do not _need_ to make any changes to your Middleware setup this version.
+
+The most basic migration will be updating the import and changing out the default export, then mirroring the previous behavior of protecting all routes as such:
+
+```diff
+- import { authMiddleware } from "@clerk/nextjs"
++ import { clerkMiddleware } from '@clerk/nextjs/server'
+
+- export default authMiddleware()
++ export default clerkMiddleware((auth) => auth().protect())
+
+  export const config = {
+    matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
+  }
+```
+
+Of course, in most cases you'll have a more complicated setup than this. You can find some examples below for how to migrate a few common use cases. Be sure to review the [`clerkMiddleware()` documentation](/docs/references/nextjs/clerk-middleware) and [route protection guide](/docs/references/nextjs/route-protection) if your specific use case is not mentioned.
+
+<Accordion titles={["Protecting all routes except one or more public paths", "Protecting a single route path", "Combining with other Middlewares (like i18n)"]} heading="h4">
+  <AccordionPanel>
+    By default, `clerkMiddleware()` treats all pages as public unless explicitly protected. If you prefer for it to operate the other way around (all pages are protected unless explicitly made public), you can reverse the middleware logic in this way:
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware } from "@clerk/nextjs"
+
+    export default authMiddleware({
+      publicRoutes: ["/", "/contact"],
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import {
+      clerkMiddleware,
+      createRouteMatcher
+    } from "@clerk/nextjs/server"
+
+    const isPublicRoute = createRouteMatcher(["/", "/contact"])
+
+    export default clerkMiddleware((auth, req) => {
+      if (isPublicRoute(req)) return // if it's a public route, do nothing
+      auth().protect() // for any other route, require auth
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    An example can be seen below of code that ensures that all routes are public except everything under `/dashboard`.
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware } from "@clerk/nextjs"
+
+    export default authMiddleware({
+      publicRoutes: (req) => !req.url.includes("/dashboard"),
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import {
+      clerkMiddleware,
+      createRouteMatcher
+    } from "@clerk/nextjs/server"
+
+    const isDashboardRoute = createRouteMatcher(["/dashboard(.*)"])
+
+    export default clerkMiddleware((auth, request) => {
+      if (isDashboardRoute(request)) auth().protect()
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    You can call other Middlewares inside `clerkMiddleware()`, giving you more direct control over what is called where. An example would be [next-intl](https://next-intl-docs.vercel.app/) to add internationalization to your app.
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware } from "@clerk/nextjs"
+    import createMiddleware from "next-intl/middleware"
+
+    const intlMiddleware = createMiddleware({
+      locales: ["en", "de"],
+      defaultLocale: "en",
+    })
+
+    export default authMiddleware({
+      beforeAuth: (req) => {
+        return intlMiddleware(req);
+      },
+      publicRoutes: ["((?!^/dashboard/).*)"],
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import {
+      clerkMiddleware,
+      createRouteMatcher
+    } from "@clerk/nextjs/server"
+    import createMiddleware from "next-intl/middleware"
+
+    const intlMiddleware = createMiddleware({
+      locales: ["en", "de"],
+      defaultLocale: "en",
+    })
+
+    const isDashboardRoute = createRouteMatcher(["/dashboard(.*)"])
+
+    export default clerkMiddleware((auth, request) => {
+      if (isDashboardRoute(request)) auth().protect()
+
+      return intlMiddleware(request)
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+</Accordion>

package/dist/guide-generators/core-2/nextjs/nextjs-version.mdx

@@ -0,0 +1,6 @@
+**Updating Next.js**
+
+`@clerk/nextjs` now requires you to use Next.js version `13.0.4` or later. Check out Next's upgrade guides for more guidance if you have not yet upgraded to Next.js 13:
+
+- [Upgrading from 12 to 13](https://nextjs.org/docs/pages/building-your-application/upgrading/version-13)
+- [Upgrading from 13 to 14](https://nextjs.org/docs/app/building-your-application/upgrading/version-14)

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

@@ -0,0 +1,23 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'core-2';
+const semverVersion = 'v5';
+const name = 'node';
+const properName = 'Node';
+const packageName = '@clerk/clerk-sdk-node';
+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 lastest version.`
+  }), `# Upgrading \`${packageName}\` to Core 2`, markdown('intro'), markdownTemplate('prepare', {
+    version: semverVersion,
+    packageName
+  }), markdown('node-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', singleItem('cjs-esm-instance'), markdown('node-setters-removals'), markdown('orgs-claim'), markdown('image-url'), accordionForCategory('image-url'), deprecationRemovalsAndHousekeeping(['pagination-return', 'pagination-args', 'error-imports'])]);
+}
+generate().then(writeToFile(cwd));

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

@@ -0,0 +1,3 @@
+Core 2 is included in the Node.js SDK starting with version 5. This new version ships with 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 Node project to use `@clerk/clerk-sdk-node` 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.