chore(*): Improve @clerk/clerk-react DX

.changeset/mighty-bulldogs-try.md

@@ -0,0 +1,34 @@
+---
+'gatsby-plugin-clerk': major
+'@clerk/chrome-extension': major
+'@clerk/nextjs': major
+'@clerk/clerk-react': major
+'@clerk/remix': major
+'@clerk/clerk-expo': major
+---
+
+- Introduce `@clerk/clerk-react/errors` and `@clerk/clerk-react/internal` subpath exports to expose some internal utilities. Eg
+    ```typescript
+    // Before
+    import { __internal__setErrorThrowerOptions } from '@clerk/clerk-react';
+    // After
+    import { setErrorThrowerOptions } from '@clerk/clerk-react/internal';
+
+    // Before
+    import { isClerkAPIResponseError, isEmailLinkError, isKnownError, isMetamaskError } from '@clerk/clerk-react';
+    // After
+    import { isClerkAPIResponseError, isEmailLinkError, isKnownError, isMetamaskError } from '@clerk/clerk-react/errors';
+
+    // Before
+    import { MultisessionAppSupport } from '@clerk/clerk-react';
+    // After
+    import { MultisessionAppSupport } from '@clerk/clerk-react/internal';
+    ```
+- Drop from the `@clerk/clerk-react` and all other clerk-react wrapper packages:
+    - `__internal__setErrorThrowerOptions` internal utility (moved to /internal subpath)
+    - `WithClerkProp` type
+    - `MultisessionAppSupport` component (moved to /internal subpath)
+    - `EmailLinkErrorCode` enum
+- Drop `StructureContext` and related errors to reduce to reduce code complexity since it seems that it was not being used.
+- Drop `withUser`, `WithUser`, `withClerk` HOFs and `WithClerk`, `withSession`, `WithSession` HOCs from the `@clerk/clerk-react` 
+  to reduce the export surface since it's trivial to implement if needed.

packages/chrome-extension/src/ClerkProvider.tsx

@@ -1,6 +1,6 @@
 import { Clerk } from '@clerk/clerk-js';
 import type { ClerkProp, ClerkProviderProps as ClerkReactProviderProps } from '@clerk/clerk-react';
-import { __internal__setErrorThrowerOptions, ClerkProvider as ClerkReactProvider } from '@clerk/clerk-react';
+import { ClerkProvider as ClerkReactProvider } from '@clerk/clerk-react';
 import React from 'react';
 
 import { buildClerk } from './singleton';
@@ -11,10 +11,6 @@ Clerk.sdkMetadata = {
   version: PACKAGE_VERSION,
 };
 
-__internal__setErrorThrowerOptions({
-  packageName: '@clerk/chrome-extension',
-});
-
 type WebSSOClerkProviderCustomProps =
   | {
       syncSessionWithTab?: false;

packages/chrome-extension/src/__snapshots__/exports.test.ts.snap

@@ -7,8 +7,6 @@ exports[`public exports should not include a breaking change 1`] = `
   "ClerkLoading",
   "ClerkProvider",
   "CreateOrganization",
-  "EmailLinkErrorCode",
-  "MultisessionAppSupport",
   "OrganizationList",
   "OrganizationProfile",
   "OrganizationSwitcher",
@@ -29,13 +27,6 @@ exports[`public exports should not include a breaking change 1`] = `
   "UserButton",
   "UserProfile",
   "WithClerk",
-  "WithSession",
-  "WithUser",
-  "__internal__setErrorThrowerOptions",
-  "isClerkAPIResponseError",
-  "isEmailLinkError",
-  "isKnownError",
-  "isMetamaskError",
   "useAuth",
   "useClerk",
   "useEmailLink",
@@ -47,7 +38,5 @@ exports[`public exports should not include a breaking change 1`] = `
   "useSignUp",
   "useUser",
   "withClerk",
-  "withSession",
-  "withUser",
 ]
 `;

packages/chrome-extension/src/index.ts

@@ -3,3 +3,7 @@ export type { StorageCache } from './utils/storage';
 
 // The order matters since we want override @clerk/clerk-react ClerkProvider
 export { ClerkProvider } from './ClerkProvider';
+
+// Override Clerk React error thrower to show that errors come from @clerk/chrome-extension
+import { setErrorThrowerOptions } from '@clerk/clerk-react/internal';
+setErrorThrowerOptions({ packageName: PACKAGE_NAME });

packages/expo/src/ClerkProvider.tsx

@@ -1,18 +1,14 @@
 import './polyfills';
 
 import type { ClerkProviderProps as ClerkReactProviderProps } from '@clerk/clerk-react';
-import { __internal__setErrorThrowerOptions, ClerkProvider as ClerkReactProvider } from '@clerk/clerk-react';
+import { ClerkProvider as ClerkReactProvider } from '@clerk/clerk-react';
 import React from 'react';
 
 import type { TokenCache } from './cache';
 import { MemoryTokenCache } from './cache';
 import { isReactNative } from './runtime';
 import { buildClerk } from './singleton';
 
-__internal__setErrorThrowerOptions({
-  packageName: '@clerk/expo',
-});
-
 export type ClerkProviderProps = ClerkReactProviderProps & {
   tokenCache?: TokenCache;
 };

packages/expo/src/index.ts

@@ -1,17 +1,8 @@
 export {
   ClerkLoaded,
   ClerkLoading,
-  EmailLinkErrorCode,
-  MultisessionAppSupport,
   SignedIn,
   SignedOut,
-  WithClerk,
-  WithSession,
-  WithUser,
-  isClerkAPIResponseError,
-  isEmailLinkError,
-  isKnownError,
-  isMetamaskError,
   useAuth,
   useClerk,
   useEmailLink,
@@ -22,12 +13,16 @@ export {
   useSignIn,
   useSignUp,
   useUser,
-  withClerk,
-  withSession,
-  withUser,
 } from '@clerk/clerk-react';
 
+export { isClerkAPIResponseError, isEmailLinkError, isKnownError, isMetamaskError } from '@clerk/clerk-react/errors';
+
 export { clerk as Clerk } from './singleton';
 
 export * from './ClerkProvider';
 export * from './useOAuth';
+
+// Override Clerk React error thrower to show that errors come from @clerk/clerk-expo
+import { setErrorThrowerOptions } from '@clerk/clerk-react/internal';
+
+setErrorThrowerOptions({ packageName: PACKAGE_NAME });

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -1,12 +1,10 @@
 import type { ClerkProviderProps } from '@clerk/clerk-react';
-import { __internal__setErrorThrowerOptions, ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
+import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
 import { navigate } from 'gatsby';
 import React from 'react';
 
 import { SDK_METADATA, TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
 
-__internal__setErrorThrowerOptions({ packageName: 'gatsby-plugin-clerk' });
-
 export type GatsbyClerkProviderProps = {
   clerkState: any;
 } & ClerkProviderProps;

packages/gatsby-plugin-clerk/src/index.ts

@@ -1 +1,5 @@
 export * from '@clerk/clerk-react';
+
+// Override Clerk React error thrower to show that errors come from gatsby-plugin-clerk
+import { setErrorThrowerOptions } from '@clerk/clerk-react/internal';
+setErrorThrowerOptions({ packageName: PACKAGE_NAME });

packages/nextjs/src/client-boundary/controlComponents.ts

@@ -10,7 +10,6 @@ export {
   RedirectToSignUp,
   RedirectToUserProfile,
   AuthenticateWithRedirectCallback,
-  MultisessionAppSupport,
   RedirectToCreateOrganization,
   RedirectToOrganizationProfile,
 } from '@clerk/clerk-react';

packages/nextjs/src/client-boundary/hooks.ts

@@ -1,9 +1,6 @@
 'use client';
 
 export {
-  WithClerk,
-  WithSession,
-  WithUser,
   useAuth,
   useClerk,
   useEmailLink,
@@ -14,17 +11,6 @@ export {
   useSignIn,
   useSignUp,
   useUser,
-  withClerk,
-  withSession,
-  withUser,
 } from '@clerk/clerk-react';
 
-export type { WithClerkProp, WithSessionProp, WithUserProp } from '@clerk/clerk-react';
-
-export {
-  EmailLinkErrorCode,
-  isClerkAPIResponseError,
-  isEmailLinkError,
-  isKnownError,
-  isMetamaskError,
-} from '@clerk/clerk-react';
+export { isClerkAPIResponseError, isEmailLinkError, isKnownError, isMetamaskError } from '@clerk/clerk-react/errors';

packages/nextjs/src/index.ts

@@ -6,7 +6,6 @@ export {
   AuthenticateWithRedirectCallback,
   ClerkLoaded,
   ClerkLoading,
-  MultisessionAppSupport,
   RedirectToCreateOrganization,
   RedirectToOrganizationProfile,
   RedirectToSignIn,
@@ -38,10 +37,6 @@ export {
  * If you do, app router will break.
  */
 export {
-  EmailLinkErrorCode,
-  WithClerk,
-  WithSession,
-  WithUser,
   isClerkAPIResponseError,
   isEmailLinkError,
   isKnownError,
@@ -56,13 +51,8 @@ export {
   useSignIn,
   useSignUp,
   useUser,
-  withClerk,
-  withSession,
-  withUser,
 } from './client-boundary/hooks';
 
-export type { WithClerkProp, WithSessionProp, WithUserProp } from './client-boundary/hooks';
-
 /**
  * Conditionally export components that exhibit different behavior
  * when used in /app vs /pages.
@@ -89,7 +79,7 @@ export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsS
 export const SignedIn = ComponentsModule.SignedIn as ServerComponentsServerModuleTypes['SignedIn'];
 export const SignedOut = ComponentsModule.SignedOut as ServerComponentsServerModuleTypes['SignedOut'];
 
-export const Protect = ComponentsModule.Protect as ServerComponentsServerModuleTypes['Protect'];
+export const Protect = ComponentsModule.Protect;
 
 export const auth = ServerHelperModule.auth as ServerHelpersServerModuleTypes['auth'];
 export const currentUser = ServerHelperModule.currentUser as ServerHelpersServerModuleTypes['currentUser'];

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -1,4 +1,6 @@
-import { __internal__setErrorThrowerOptions, ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
+import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
+// Override Clerk React error thrower to show that errors come from @clerk/nextjs
+import { setErrorThrowerOptions } from '@clerk/clerk-react/internal';
 import { useRouter } from 'next/router';
 import React from 'react';
 
@@ -7,8 +9,7 @@ import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
-
-__internal__setErrorThrowerOptions({ packageName: '@clerk/nextjs' });
+setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
   const { __unstable_invokeMiddlewareOnAuthStateChange = true } = props;
@@ -40,7 +41,6 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
 
   return (
     <ClerkNextOptionsProvider options={mergedProps}>
-      {/*@ts-expect-error*/}
       <ReactClerkProvider
         {...mergedProps}
         initialState={initialState}

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -3,7 +3,8 @@ import { isTruthy } from '@clerk/shared/underscore';
 import { SDK_METADATA } from '../server/constants';
 import type { NextClerkProviderProps } from '../types';
 
-export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, 'children'>) => {
+// @ts-ignore - https://github.com/microsoft/TypeScript/issues/47663
+export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, 'children'>): any => {
   return {
     ...props,
     publishableKey: props.publishableKey || process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY || '',

packages/react/.gitignore

@@ -0,0 +1,2 @@
+/*/
+!/src/

packages/react/jest.config.js

@@ -1,4 +1,4 @@
-const { name } = require('./package.json');
+const { name, version } = require('./package.json');
 
 module.exports = {
   displayName: name.replace('@clerk', ''),
@@ -15,4 +15,10 @@ module.exports = {
 
   testRegex: ['/ui/.*/__tests__/.*.test.[jt]sx?$', '/.*.test.[jt]sx?$'],
   testPathIgnorePatterns: ['/node_modules/'],
+
+  globals: {
+    __DEV__: true,
+    PACKAGE_NAME: name,
+    PACKAGE_VERSION: version,
+  },
 };

packages/react/package.json

@@ -33,15 +33,37 @@
         "default": "./dist/index.js"
       }
     },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.mts",
+        "default": "./dist/internal.mjs"
+      },
+      "require": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/errors.d.mts",
+        "default": "./dist/errors.mjs"
+      },
+      "require": {
+        "types": "./dist/errors.d.ts",
+        "default": "./dist/errors.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "internal",
+    "errors"
   ],
   "scripts": {
     "build": "tsup",
+    "postbuild": "node ../../scripts/subpath-workaround.mjs react",
     "clean": "rimraf ./dist",
     "dev": "tsup --watch",
     "dev:publish": "npm run dev -- --env.publish",

packages/react/src/components/controlComponents.tsx

@@ -9,7 +9,6 @@ import React from 'react';
 import { useAuthContext } from '../contexts/AuthContext';
 import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
 import { useSessionContext } from '../contexts/SessionContext';
-import { LoadedGuarantee } from '../contexts/StructureContext';
 import { useAuth } from '../hooks';
 import { useAssertWrappedByClerkProvider } from '../hooks/useAssertWrappedByClerkProvider';
 import type { RedirectToSignInProps, RedirectToSignUpProps, WithClerkProp } from '../types';
@@ -42,7 +41,7 @@ export const ClerkLoaded = ({ children }: React.PropsWithChildren<unknown>): JSX
   if (!isomorphicClerk.loaded) {
     return null;
   }
-  return <LoadedGuarantee>{children}</LoadedGuarantee>;
+  return <>{children}</>;
 };
 
 export const ClerkLoading = ({ children }: React.PropsWithChildren<unknown>): JSX.Element | null => {

packages/react/src/components/index.ts

@@ -19,14 +19,11 @@ export {
   RedirectToSignUp,
   RedirectToUserProfile,
   AuthenticateWithRedirectCallback,
-  MultisessionAppSupport,
   RedirectToCreateOrganization,
   RedirectToOrganizationProfile,
 } from './controlComponents';
 
 export * from './withClerk';
-export * from './withUser';
-export * from './withSession';
 
 export * from './SignInButton';
 export * from './SignUpButton';

packages/react/src/components/uiComponents.tsx

@@ -18,7 +18,7 @@ import {
   organizationProfilePageRenderedError,
   userProfileLinkRenderedError,
   userProfilePageRenderedError,
-} from '../errors';
+} from '../errors/messages';
 import type {
   MountProps,
   OrganizationProfileLinkProps,