@clerk/upgrade 0.2.0 → 0.3.0

package/dist/guide-generators/v5/generate.js

@@ -0,0 +1,263 @@
+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);
+
+  // Shared sections:
+  // - path routing
+  // - org claim removed
+  // - afterSignX changes
+  // - error import changes
+  // - hof removals
+  // - imageUrl changes
+
+  // ------------------------------------------------------------
+
+  // 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';
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.gatsby);
+
+  // Shared sections:
+  // - path routing
+  // - org claim removed
+  // - afterSignX changes
+  // - error import changes
+  // - hof removals
+  // - imageUrl changes
+
+  // ------------------------------------------------------------
+
+  output += '### Expo';
+  output += '\n\n';
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.expo);
+
+  // Shared sections:
+  // - org claim removed
+  // - afterSignX changes
+  // - error import changes
+  // - hof removals
+  // - imageUrl changes
+
+  // ------------------------------------------------------------
+
+  output += '### Fastify';
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.fastify);
+
+  // Shared sections:
+  // - org claim removed
+  // - imageUrl changes
+
+  // ------------------------------------------------------------
+
+  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);
+
+  // Shared sections:
+  // - org claim removed
+  // - imageUrl changes
+
+  // ------------------------------------------------------------
+
+  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';
+
+  // Components redesigned
+  output += renderMarkdown('v5-guide/redesign-preview');
+  output += '\n\n';
+
+  // Deprecation removals & housekeeping
+  output += renderDeprecationRemovalsAndHousekeeping(data.react);
+
+  // Shared sections:
+  // - path routing?
+  // - org claim removed
+  // - afterSignX changes
+  // - error import changes
+  // - hof removals
+  // - imageUrl changes
+
+  // ------------------------------------------------------------
+
+  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';
+
+  // imageUrl changes
+
+  // createOrganization args
+
+  // attemptweb3wallet
+
+  // afterSignXUrl changes
+
+  // Deprecation removals & housekeeping
+
+  // Shared sections:
+  // - path routing?
+  // - org claim removed
+  // - afterSignX changes
+  // - error import changes
+
+  // ------------------------------------------------------------
+
+  output += '### Backend';
+  output += '\n\n';
+
+  // buildrequesturl, createisomorphicrequest, createEmail removed
+
+  // clockskewinms
+
+  // error api import move
+
+  // membershiprole -> organizationcustomrolekey
+
+  // orgs claim dropped
+
+  // Deprecation removals & housekeeping
+
+  // ------------------------------------------------------------
+
+  output += '### Chrome Extension';
+  output += '\n\n';
+
+  // token cache change
+
+  // ------------------------------------------------------------
+
+  // 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/guide-generators/v5/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.