@clerk/upgrade 0.2.0 → 0.3.0

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

@@ -0,0 +1,472 @@
+---
+title: "Upgrading Gatsby from v4 to v5"
+description: "Learn how to upgrade Clerk's Gatsby SDK from v4 to v5."
+---
+
+# Upgrading `gatsby-plugin-clerk` from v4 to v5
+
+Version 5 of the Gatsby SDK 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 Expo 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.
+
+## Preparing to upgrade
+
+Before uprading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (`npm i gatsby-plugin-clerk@core-1`). Some changes required for Core 2 can be applied incrementally to the latest v5 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.
+
+**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).
+
+**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.
+
+## 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 gatsby-plugin-clerk@beta
+    ```
+
+    ```bash filename="terminal"
+    yarn add gatsby-plugin-clerk@beta
+    ```
+
+    ```bash filename="terminal"
+    pnpm add gatsby-plugin-clerk@beta
+    ```
+
+</CodeBlockTabs>
+
+## 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, 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.
+
+## Breaking Changes
+
+### 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 &raquo;](/components-redesigned)
+
+### 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 />
+```
+
+### 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.
+
+### 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" />
+```
+
+
+
+### 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:
+
+<Accordion titles={["<code>Organization.logoUrl</code> -&gt; <code>Organization.imageUrl</code>", "<code>User.profileImageUrl</code> -&gt; <code>.imageUrl</code>", "<code>ExternalAccount.avatarUrl</code> -&gt; <code>.imageUrl</code>", "<code>OrganizationMembershipPublicUserData.profileImageUrl</code> -&gt; <code>.imageUrl</code>"]}>
+  <AccordionPanel>    
+    The `logoUrl` property of any [`Organization` object](https://clerk.com/docs/references/javascript/organization/organization#organization) has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profileImageUrl` property of any `User` object has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `avatarUrl` property of any [`ExternalAcccount` object](https://clerk.com/docs/references/javascript/external-account) has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profileImageUrl` property of any `OrganizationMembershipPublicUserData` object has been changed to `imageUrl`.
+  </AccordionPanel>
+</Accordion>
+
+### Deprecation removals & housekeeping
+
+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>
+
+#### Deprecation removals
+
+<Accordion titles={["<code>User.update({ password: &#39;x&#39; })</code> -&gt; <code>User.updatePassword(&#39;x&#39;)</code>", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as prop to <code>ClerkProvider</code>", "<code>afterSwitchOrganizationUrl</code> -&gt; <code>afterSelectOrganizationUrl</code> in <code>OrganizationSwitcher</code>", "<code>ClerkProviderOptionsWrapper</code> type removed", "<code>CLERK_API_KEY</code> replaced by <code>CLERK_SECRET_KEY</code>", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to createClerkClient", "<code>GASTBY_CLERK_FRONTEND_API</code> replaced by <code>GATSBY_CLERK_PUBLISHABLE_KEY</code>", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to createClerkClient"]}>
+  <AccordionPanel>    
+    If you are updating a user's password via the [`User.update` method](https://clerk.com/docs/references/javascript/user/user#update), it must be changed to [`User.updatePassword`](https://clerk.com/docs/references/javascript/user/password-management#update-password) instead. This method will require the current password as well as the desired new password. We made this update to improve the security of password changes. Example below:
+    
+    ```diff
+    - user.update({ password: 'foo' });
+    
+    + user.updatePassword({
+    +   currentPassword: 'bar',
+    +   newPassword: 'foo',
+    +   signOutOfOtherSessions: true,
+    + });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` prop passed to `<ClerkProvider>` was renamed to `publishableKey`. **Note:** The values are different, so this is not just a key replacement. You can visit your [Clerk dashboard](https://dashboard.clerk.com/last-active?path=api-keys) to copy/paste the new keys after choosing your framework. Make sure to update this in all environments (e.g. dev, staging, production). [More information](/docs/deployments/overview#api-keys-and-environment-variables).
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `afterSwitchOrganizationUrl` prop on the `<OrganizationSwitcher />` component has been renamed to `afterSelectOrganizationUrl`. This is a quick and simple rename.
+    
+    ```diff
+    - <OrganizationSwitcher afterSwitchOrganizationUrl='...' />
+    + <OrganizationSwitcher afterSelectOrganizationUrl='...' />
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    This type was extending `ClerkProviderProps` with but was not necessary. This type is typically used internally and is not required to be imported and used directly. If needed, import and use `ClerkProviderProps` instead.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `CLERK_API_KEY` environment variable was renamed to `CLERK_SECRET_KEY`. You can visit your [Clerk dashboard](https://dashboard.clerk.com/last-active?path=api-keys) to copy/paste the new keys after choosing your framework. Make sure to update this in all environments (e.g. dev, staging, production).
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `createClerkClient` must be changed to `secretKey`.
+    
+    ```diff
+    import { createClerkClient } from 'gatsby-plugin-clerk/api';
+    
+    - createClerkClient({ apiKey: '...' });
+    + createClerkClient({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    If you are using a `GATSBY_CLERK_FRONTEND_API` environment variable, the name must be changed to `GATSBY_CLERK_PUBLISHABLE_KEY` instead. Note that the values are different as well, so this is not just a key replacement. You can find the publishable key in your Clerk dashboard. Make sure you do this in both your dev and production environments.
+  </AccordionPanel>
+  <AccordionPanel>    
+    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.
+    
+    ```diff
+    import { createClerkClient } from 'gatsby-plugin-clerk/api';
+    
+    - createClerkClient({ frontendApi: '...' });
+    + createClerkClient({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+</Accordion>
+
+#### Other Breaking Changes
+
+<Accordion titles={["<code>MagicLinkErrorCode</code> -&gt; <code>EmailLinkErrorCode</code>", "<code>useMagicLink</code> -&gt; <code>useEmailLink</code>", "<code>isMagicLinkError</code> -&gt; <code>isEmailLinkError</code>", "<code>MagicLinkError</code> -&gt; <code>EmailLinkError</code>", "<code>handleMagicLinkVerification</code> -&gt; <code>handleEmailLinkVerification</code>", "<code>setSession</code> -&gt; <code>setActive</code>", "<code>invitationList</code> -&gt; <code>invitations</code> as param to <code>useOrganizations</code>", "<code>membershipList</code> -&gt; <code>members</code> as param to <code>useOrganization</code>", "<code>useOrganizations</code> -&gt; <code>useOrganizationList</code>", "<code>userProfile</code> -&gt; <code>userProfileProps</code> for <code>UserButton</code>", "<code>MultisessionAppSupport</code> import moved to <code>/internal</code>", "Replace <code>signOutCallback</code> prop on <code>SignOutButton</code> with <code>redirectUrl</code>", "<code>API_URL</code> value has changed", "<code>withServerAuth</code> props.auth return type changed", "<code>Clerk</code> -&gt; <code>{ createClerkClient }</code>"]}>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    `setSession` should be replaced with `setActive`. The format of the parameters has changed slightly - `setActive` takes an object where `setSession` took params directly. The `setActive` function also can accept an `organization` param that is used to set the currently active organization. The return signature did not change. Read the [API documentation](/docs/references/javascript/clerk/session-methods#set-active) for more detail. This function should be expected to be returned from one of the following Clerk hooks: `useSessionList`, `useSignUp`, or `useSignIn`. Some migration examples:
+    
+    ```diff
+    - await setSession('sessionID', () => void)
+    + await setActive({ session: 'sessionID',  beforeEmit: () => void })
+    
+    - await setSession(sessionObj)
+    + await setActive({ session: sessionObj })
+    
+    - await setSession(sessionObj, () => void)
+    + await setActive({ session: sessionObj,  beforeEmit: () => void })
+    ```
+    
+    `setActive` also supports setting an active organization:
+    
+    ```js
+    await setActive({
+      session: 'sessionID',
+      organization: 'orgID',
+      beforeEmit: () => void
+    })
+    
+    await setActive({
+      session: sessionObj,
+      organization: orgObj,
+      beforeEmit: () => void
+    })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `invitationList` param to the `useOrganizations` hook has been replaced by `invitations`. This param also has a slightly different way of working, examples included below. Note also that `useOrganizations` is deprecated and should be updated to `useOrganization` instead.
+    
+    ```js
+    // before
+    const { invitationList } = useOrganization({
+    	invitationList: { limit: 10, offset: 1 },
+    });
+    
+    // after
+    const { invitations } = useOrganization({
+    	invitations: {
+    		initialPage: 1,
+    		pageSize: 10,
+    	},
+    });
+    
+    // you can also simply return all invitations
+    const { invitations } = useOrganization({ invitations: true });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `membershipList` param from the `useOrganization` hook has been removed. Instead, [use the `memberships` param](https://clerk.com/docs/references/react/use-organization#parameters). Examples of each can be seen here:
+    
+    ```js
+    // before
+    const { membershipList } = useOrganization({
+    	membershipList: { limit: 10, offset: 1 },
+    });
+    
+    // after
+    const { memberships } = useOrganization({
+    	memberships: {
+    		initialPage: 1,
+    		pageSize: 10,
+    	},
+    });
+    
+    // you can also simply return all memberships
+    const { memberships } = useOrganization({ memberships: true });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    Any place where `useOrganizations` is used should be switched to [`useOrganizationList`](https://clerk.com/docs/references/react/use-organization-list) or [`useOrganization`](https://clerk.com/docs/references/react/use-organization) instead. The return signature has also changed, so take note of this when making the upgrade.
+    
+    ```js
+    // before: useOrganizations return values
+    {
+        isLoaded: boolean,
+        createOrganization: clerk.createOrganization,
+        getOrganizationMemberships: clerk.getOrganizationMemberships,
+        getOrganization: clerk.getOrganization,
+    }
+    
+    // after: useOrganizationList return values
+    {
+        isLoaded: boolean,
+        createOrganization: clerk.createOrganization,
+        userMemberships: PaginatedResourcesWithDefault<...> | PaginatedResources<...>,
+        userInvitations: PaginatedResourcesWithDefault<...> | PaginatedResources<...>,
+        userSuggestions: PaginatedResourcesWithDefault<...> | PaginatedResources<...>,
+        setActive: clerk.setActive,
+    }
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `userProfile` prop on [the `UserButton` component](https://clerk.com/docs/references/javascript/clerk/user-button#user-button-component) has been changed to `userProfileProps`. This is purely a name change, none of the values need to be updated.
+    
+    ```diff
+    - <UserButton userProfile={} />
+    + <UserButton userProfileProps={} />
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    `MultiSessionAppSupport` is a component that handles the intermediate “undefined” state for multisession apps by unmounting and remounting the components during the session switch (`setActive` call) in order to solve theoretical edge-cases that can arise while switching sessions. It is undocumented and intended only for internal use, so it has been moved to an `/internal` import path. Please note that internal imports are not intended for public use, and are outside the scope of semver.
+    
+    ```diff
+    - import { MultiSessionAppSupport } from '@clerk/clerk-react'
+    + import { MultiSessionAppSupport } from '@clerk/clerk-react/internal'
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `signOutCallback` prop on the [`<SignOutButton />` component](https://clerk.com/docs/components/unstyled/sign-out-button) has been removed. Instead, you can use the `redirectUrl` prop. Example below:
+    
+    ```diff
+      import { SignOutButton } from "@clerk/clerk-react";
+    
+      export const Signout = () => {
+        return (
+          <SignOutButton
+    -       signOutCallback={() => { window.location.href = "/your-path" }}
+    +       redirectUrl="/your-path"
+          >
+            <button>Sign Out</button>
+          </SignOutButton>
+        )
+      }
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The value of this export has changed from `https://api.clerk.dev` to `https://api.clerk.com`. If you were relying on the text content of this value not changing, you may need to make adjustments.
+  </AccordionPanel>
+  <AccordionPanel>    
+    When utilizing the `withServerAuth` helper in Gatsby, it expects a callback function that is called with props from Clerk internals. The `.auth` property on the returned object from the callback has seen a substantial change in its return type. Below is a code example of where the `auth` prop might be found:
+    
+    ```js
+    import { withServerAuth } from 'gatsby-plugin-clerk/ssr';
+    
+    export const getServerData: GetServerData<any> = withServerAuth(async props => {
+      return { props: { data: '...', auth: props.auth } };
+    });
+    ```
+    
+    And here's a diff of the changes in the return type. The breaking change here specifically is that the property `auth.claims` was changed to `auth.sessionClaims`. Additionally, there is more information on the response that can be utilized if helpful.
+    
+    ```diff
+     // return type diff
+     {
+       sessionId: string | null;
+       userId: string | null;
+       actor: ActJWTClaim | null;
+       getToken: ServerGetToken;
+    -  claims: ClerkJWTClaims | null;
+    +  sessionClaims: JwtPayload;
+    +  session: Session | undefined | null;
+    +  user: User | undefined | null;
+    +  orgId: string | undefined | null;
+    +  orgRole: string | undefined | null;
+    +  orgSlug: string | undefined | null;
+    +  organization: Organization | undefined | null;
+    +  debug: AuthObjectDebug;
+     };
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `Clerk` default import has changed to `createClerkClient` and been moved to a named import rather than default. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import Clerk from "gatsby-plugin-clerk"
+    + import { createClerkClient } from "gatsby-plugin-clerk"
+    ```
+  </AccordionPanel>
+</Accordion>
+
+
+

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

@@ -0,0 +1,24 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, writeToFile } from '../../text-generation.js';
+const version = '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} from v4 to v5`,
+    description: `Learn how to upgrade Clerk's ${properName} SDK from v4 to v5.`
+  }), `# Upgrading \`${packageName}\` from v4 to v5`, markdown('intro'), markdownTemplate('prepare', {
+    version,
+    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/v5/gatsby/intro.mdx

@@ -0,0 +1,3 @@
+Version 5 of the Gatsby SDK 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 Expo 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/v5/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/chromeExtension/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