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;