chore(ui,astro): improve error handling, build config, and code organization

UI Package Updates:
- Enhanced billing error handling in CheckoutPage by properly flattening
  ClerkAPIResponseErrors to extract error codes
- Updated InvalidPlanScreen to correctly filter and extract errors from
  ClerkAPIResponseErrors before checking for invalid_plan_change
- Removed unused imports from OrganizationProfile components
- Simplified SignUpStart appearance usage
- Added type-check script to package.json
- Updated tsconfig to exclude __tests__ directories
- Enhanced rspack dev config with better source maps and disabled tree shaking
  for easier debugging
- Added __BUILD_DISABLE_RHC__ constant to both rspack and tsdown configs

Astro Package Updates:
- Refactored createClerkInstance to extract clerk-js and clerk-ui loading into
  separate functions (getClerkJsEntryChunk, getClerkUiEntryChunk)
- Improved code clarity with better comments explaining early returns when
  scripts are already loaded via middleware
- Maintained parallel loading of both scripts for optimal performance

Root Package Updates:
- Added E2E_DEBUG=1 to billing, generic, and machine integration test scripts
  for better debugging visibility
- Updated billing test to use withBillingJwtV2 instead of withBilling
- Fixed duplicate E2E_DEBUG flag in express test script

Author: nikosdouvlis

package.json

@@ -34,17 +34,17 @@
     "test:integration:ap-flows": "pnpm test:integration:base --grep @ap-flows",
     "test:integration:astro": "E2E_APP_ID=astro.* pnpm test:integration:base --grep @astro",
     "test:integration:base": "pnpm playwright test --config integration/playwright.config.ts",
-    "test:integration:billing": "E2E_APP_ID=withBilling.* pnpm test:integration:base --grep @billing",
+    "test:integration:billing": "E2E_DEBUG=1 E2E_APP_ID=withBillingJwtV2.* pnpm test:integration:base --grep @billing",
     "test:integration:cleanup": "pnpm playwright test --config integration/playwright.cleanup.config.ts",
     "test:integration:custom": "pnpm test:integration:base --grep @custom",
     "test:integration:deployment:nextjs": "pnpm playwright test --config integration/playwright.deployments.config.ts",
     "test:integration:expo-web:disabled": "E2E_APP_ID=expo.expo-web pnpm test:integration:base --grep @expo-web",
-    "test:integration:express": "E2E_DEBUG=1 E2E_APP_ID=express.* pnpm test:integration:base --grep @express",
-    "test:integration:generic": "E2E_APP_ID=react.vite.*,next.appRouter.withEmailCodes* pnpm test:integration:base --grep @generic",
+    "test:integration:express": "E2E_DEBUG=1 E2E_DEBUG=1 E2E_APP_ID=express.* pnpm test:integration:base --grep @express",
+    "test:integration:generic": "E2E_DEBUG=1 E2E_APP_ID=react.vite.*,next.appRouter.withEmailCodes* pnpm test:integration:base --grep @generic",
     "test:integration:handshake": "DISABLE_WEB_SECURITY=true E2E_APP_1_ENV_KEY=sessions-prod-1 E2E_SESSIONS_APP_1_HOST=multiple-apps-e2e.clerk.app pnpm test:integration:base --grep @handshake",
     "test:integration:handshake:staging": "DISABLE_WEB_SECURITY=true E2E_APP_1_ENV_KEY=clerkstage-sessions-prod-1 E2E_SESSIONS_APP_1_HOST=clerkstage-sessions-prod-1-e2e.clerk.app pnpm test:integration:base --grep @handshake",
     "test:integration:localhost": "pnpm test:integration:base --grep @localhost",
-    "test:integration:machine": "E2E_APP_ID=withMachine.* pnpm test:integration:base --grep @machine",
+    "test:integration:machine": "E2E_DEBUG=1 pnpm test:integration:base --grep @machine",
     "test:integration:nextjs": "E2E_APP_ID=next.appRouter.* pnpm test:integration:base --grep @nextjs",
     "test:integration:nuxt": "E2E_DEBUG=1 E2E_APP_ID=nuxt.node npm run test:integration:base -- --grep @nuxt",
     "test:integration:quickstart": "E2E_APP_ID=quickstart.* pnpm test:integration:base --grep @quickstart",

packages/astro/src/internal/create-clerk-instance.ts

@@ -36,30 +36,20 @@ function createNavigationHandler(
 const createClerkInstance = runOnce(createClerkInstanceInternal);
 
 async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroClerkCreateInstanceParams<TUi>) {
-  let clerkJSInstance = window.Clerk;
-  let clerkUiCtor: Promise<ClerkUiConstructor> | undefined;
-
-  if (!clerkJSInstance) {
-    // Load both clerk-js and clerk-ui in parallel
-    const clerkPromise = loadClerkJsScript(options);
-    clerkUiCtor = options?.clerkUiCtor
-      ? Promise.resolve(options.clerkUiCtor)
-      : loadClerkUiScript(options).then(() => {
-          if (!window.__internal_ClerkUiCtor) {
-            throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
-          }
-          // After the check, TypeScript knows it's defined
-          return window.__internal_ClerkUiCtor;
-        });
-
-    await clerkPromise;
-
-    if (!window.Clerk) {
-      throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
-    }
-    clerkJSInstance = window.Clerk;
+  // Load clerk-js and clerk-ui in parallel.
+  // Both functions return early if the scripts are already loaded
+  // (e.g., via middleware-injected script tags in the HTML head).
+  const clerkJsChunk = getClerkJsEntryChunk(options);
+  const clerkUiCtor = getClerkUiEntryChunk(options);
+
+  await clerkJsChunk;
+
+  if (!window.Clerk) {
+    throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
   }
 
+  const clerkJSInstance = window.Clerk;
+
   if (!$clerk.get()) {
     $clerk.set(clerkJSInstance);
   }
@@ -110,4 +100,32 @@ function updateClerkOptions<TUi extends Ui = Ui>(options: AstroClerkUpdateOption
   void (clerk as any).__internal_updateProps(updateOptions);
 }
 
+/**
+ * Loads clerk-js script if not already loaded.
+ * Returns early if window.Clerk already exists.
+ */
+async function getClerkJsEntryChunk<TUi extends Ui = Ui>(options?: AstroClerkCreateInstanceParams<TUi>): Promise<void> {
+  await loadClerkJsScript(options);
+}
+
+/**
+ * Gets the ClerkUI constructor, either from options or by loading the script.
+ * Returns early if window.__internal_ClerkUiCtor already exists.
+ */
+async function getClerkUiEntryChunk<TUi extends Ui = Ui>(
+  options?: AstroClerkCreateInstanceParams<TUi>,
+): Promise<ClerkUiConstructor> {
+  if (options?.clerkUiCtor) {
+    return options.clerkUiCtor;
+  }
+
+  await loadClerkUiScript(options);
+
+  if (!window.__internal_ClerkUiCtor) {
+    throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
+  }
+
+  return window.__internal_ClerkUiCtor;
+}
+
 export { createClerkInstance, updateClerkOptions };

packages/ui/package.json

@@ -62,7 +62,8 @@
     "showerrors": "tsc",
     "test:ci": "vitest --maxWorkers=70%",
     "test:coverage": "vitest --collectCoverage && open coverage/lcov-report/index.html",
-    "test:disabled": "vitest"
+    "test:disabled": "vitest",
+    "type-check": "tsc --noEmit"
   },
   "dependencies": {
     "@clerk/localizations": "workspace:^",

packages/ui/rspack.config.js

@@ -44,6 +44,7 @@ const common = ({ mode, variant }) => {
         PACKAGE_VERSION: JSON.stringify(packageJSON.version),
         __PKG_VERSION__: JSON.stringify(packageJSON.version),
         PACKAGE_NAME: JSON.stringify(packageJSON.name),
+        __BUILD_DISABLE_RHC__: JSON.stringify(false),
       }),
       new rspack.EnvironmentPlugin({
         NODE_ENV: mode,
@@ -166,7 +167,7 @@ const devConfig = (mode, env) => {
       rules: [svgLoader(), ...typescriptLoaderDev()],
     },
     plugins: [new ReactRefreshPlugin({ overlay: { sockHost: devUrl.host } })],
-    devtool: 'eval-cheap-source-map',
+    devtool: 'eval-source-map',
     output: {
       publicPath: `${devUrl.origin}/npm/`,
       crossOriginLoading: 'anonymous',
@@ -175,6 +176,8 @@ const devConfig = (mode, env) => {
     },
     optimization: {
       minimize: false,
+      usedExports: false,
+      providedExports: false,
     },
     devServer: {
       allowedHosts: ['all'],

packages/ui/src/components/Checkout/CheckoutPage.tsx

@@ -61,7 +61,11 @@ const FetchStatus = ({
 
   const internalFetchStatus = useMemo(() => {
     if (errors.global) {
-      const errorCodes = errors.global.map(e => e.code);
+      const errorCodes = errors.global.flatMap(e => {
+        if (e.isClerkApiResponseError()) {
+          return e.errors.map(e => e.code);
+        }
+      });
 
       if (errorCodes.includes('missing_payer_email')) {
         return 'missing_payer_email';

packages/ui/src/components/Checkout/parts.tsx

@@ -41,12 +41,15 @@ export const InvalidPlanScreen = () => {
   const { planPeriod } = useCheckoutContext();
   const { errors } = useCheckout();
 
-  const InvalidPlanError = errors?.global?.find(e => e.code === 'invalid_plan_change');
+  const InvalidPlanError = errors?.global
+    ?.filter(e => e.isClerkApiResponseError())
+    .flatMap(e => e.errors)
+    .find(e => e.code === 'invalid_plan_change');
+
   if (!InvalidPlanError) {
     return null;
   }
 
-  // @ts-expect-error - meta is not a property of FieldError
   const { plan: planFromError, isPlanUpgradePossible } = InvalidPlanError?.meta || {};
 
   return (

packages/ui/src/components/OrganizationProfile/InviteMembersScreen.tsx

@@ -1,18 +1,15 @@
 import { useOrganization } from '@clerk/shared/react';
-import { runIfFunctionOrReturn } from '@clerk/shared/utils';
 
 import { useCardState, withCardStateProvider } from '@/ui/elements/contexts';
 import { FormContainer } from '@/ui/elements/FormContainer';
 import { IconCircle } from '@/ui/elements/IconCircle';
 import { SuccessPage } from '@/ui/elements/SuccessPage';
 
 import { useWizard, Wizard } from '../../common';
-import { useOrganizationProfileContext } from '../../contexts';
 import { descriptors, Flex, localizationKeys, Text } from '../../customizables';
 import { useActionContext } from '../../elements/Action/ActionRoot';
 import { Email } from '../../icons';
 import { InviteMembersForm } from './InviteMembersForm';
-
 type InviteMembersScreenProps = {
   onReset?: () => void;
 };

packages/ui/src/components/OrganizationProfile/OrganizationMembers.tsx

@@ -8,7 +8,7 @@ import { Header } from '@/ui/elements/Header';
 import { Tab, TabPanel, TabPanels, Tabs, TabsList } from '@/ui/elements/Tabs';
 
 import { NotificationCountBadge, useProtect } from '../../common';
-import { useEnvironment, useOrganizationProfileContext } from '../../contexts';
+import { useEnvironment } from '../../contexts';
 import { Col, descriptors, Flex, localizationKeys } from '../../customizables';
 import { Action } from '../../elements/Action';
 import { mqu } from '../../styledSystem';

packages/ui/tsconfig.json

@@ -29,6 +29,6 @@
       "@/ui*": ["./src/*"]
     }
   },
-  "exclude": ["node_modules", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"],
+  "exclude": ["node_modules", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx", "**/__tests__/**"],
   "include": ["src", "src/global.d.ts"]
 }

packages/ui/tsdown.config.mts

@@ -20,6 +20,7 @@ export default defineConfig(({ watch }) => {
       PACKAGE_VERSION: `"${uiPackage.version}"`,
       __PKG_VERSION__: `"${uiPackage.version}"`,
       __DEV__: `${watch}`,
+      __BUILD_DISABLE_RHC__: JSON.stringify(false),
     },
   } satisfies Options;