feat(clerk-js): Add cssLayerName option to experimental_createTheme

packages/clerk-js/src/core/clerk.ts

@@ -112,6 +112,7 @@ import {
   isRedirectForFAPIInitiatedFlow,
   noOrganizationExists,
   noUserExists,
+  processCssLayerNameExtraction,
   removeClerkQueryParam,
   requiresUserInput,
   sessionExistsAndSingleSessionModeEnabled,
@@ -2727,9 +2728,18 @@ export class Clerk implements ClerkInterface {
   };
 
   #initOptions = (options?: ClerkOptions): ClerkOptions => {
+    const processedOptions = options ? { ...options } : {};
+
+    // Extract cssLayerName from baseTheme if present and move it to appearance level
+    if (processedOptions.appearance) {
+      processedOptions.appearance = processCssLayerNameExtraction(processedOptions.appearance);
+    }
+
+    console.log('processedOptions', processedOptions);
+
     return {
       ...defaultOptions,
-      ...options,
+      ...processedOptions,
       allowedRedirectOrigins: createAllowedRedirectOrigins(
         options?.allowedRedirectOrigins,
         this.frontendApi,

packages/clerk-js/src/utils/__tests__/appearance.spec.ts

@@ -0,0 +1,173 @@
+import type { Appearance, BaseTheme } from '@clerk/types';
+import { describe, expect, it } from 'vitest';
+
+import { processCssLayerNameExtraction } from '../appearance';
+
+describe('processCssLayerNameExtraction', () => {
+  it('extracts cssLayerName from single baseTheme and moves it to appearance level', () => {
+    const appearance: Appearance = {
+      baseTheme: {
+        __type: 'prebuilt_appearance' as const,
+        cssLayerName: 'theme-layer',
+      },
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBe('theme-layer');
+    expect(result?.baseTheme).toBeDefined();
+    if (result?.baseTheme && !Array.isArray(result.baseTheme)) {
+      expect((result.baseTheme as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+      expect(result.baseTheme.__type).toBe('prebuilt_appearance');
+    }
+  });
+
+  it('preserves appearance-level cssLayerName over baseTheme cssLayerName', () => {
+    const appearance: Appearance = {
+      cssLayerName: 'appearance-layer',
+      baseTheme: {
+        __type: 'prebuilt_appearance' as const,
+        cssLayerName: 'theme-layer',
+      },
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBe('appearance-layer');
+    if (result?.baseTheme && !Array.isArray(result.baseTheme)) {
+      expect((result.baseTheme as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+    }
+  });
+
+  it('extracts cssLayerName from first theme in array that has one', () => {
+    const appearance: Appearance = {
+      baseTheme: [
+        {
+          __type: 'prebuilt_appearance' as const,
+        },
+        {
+          __type: 'prebuilt_appearance' as const,
+          cssLayerName: 'first-layer',
+        },
+        {
+          __type: 'prebuilt_appearance' as const,
+          cssLayerName: 'second-layer',
+        },
+      ],
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBe('first-layer');
+    expect(result?.baseTheme).toBeDefined();
+    if (result?.baseTheme && Array.isArray(result.baseTheme)) {
+      expect(result.baseTheme).toHaveLength(3);
+      expect((result.baseTheme[0] as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+      expect((result.baseTheme[1] as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+      expect((result.baseTheme[2] as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+      result.baseTheme.forEach(theme => {
+        expect(theme.__type).toBe('prebuilt_appearance');
+      });
+    }
+  });
+
+  it('preserves appearance-level cssLayerName over array baseTheme cssLayerName', () => {
+    const appearance: Appearance = {
+      cssLayerName: 'appearance-layer',
+      baseTheme: [
+        {
+          __type: 'prebuilt_appearance' as const,
+          cssLayerName: 'theme1-layer',
+        },
+        {
+          __type: 'prebuilt_appearance' as const,
+          cssLayerName: 'theme2-layer',
+        },
+      ],
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBe('appearance-layer');
+    if (result?.baseTheme && Array.isArray(result.baseTheme)) {
+      result.baseTheme.forEach(theme => {
+        expect((theme as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+      });
+    }
+  });
+
+  it('handles single baseTheme without cssLayerName', () => {
+    const appearance: Appearance = {
+      baseTheme: {
+        __type: 'prebuilt_appearance' as const,
+      },
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBeUndefined();
+    if (result?.baseTheme && !Array.isArray(result.baseTheme)) {
+      expect(result.baseTheme.__type).toBe('prebuilt_appearance');
+      expect((result.baseTheme as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+    }
+  });
+
+  it('handles array of baseThemes without any cssLayerName', () => {
+    const appearance: Appearance = {
+      baseTheme: [
+        {
+          __type: 'prebuilt_appearance' as const,
+        },
+        {
+          __type: 'prebuilt_appearance' as const,
+        },
+      ],
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBeUndefined();
+    if (result?.baseTheme && Array.isArray(result.baseTheme)) {
+      expect(result.baseTheme).toHaveLength(2);
+      result.baseTheme.forEach(theme => {
+        expect(theme.__type).toBe('prebuilt_appearance');
+        expect((theme as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+      });
+    }
+  });
+
+  it('handles no baseTheme provided', () => {
+    const appearance: Appearance = {
+      cssLayerName: 'standalone-layer',
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBe('standalone-layer');
+    expect(result?.baseTheme).toBeUndefined();
+  });
+
+  it('handles undefined appearance', () => {
+    const result = processCssLayerNameExtraction(undefined);
+
+    expect(result).toBeUndefined();
+  });
+
+  it('preserves other appearance properties', () => {
+    const appearance: Appearance = {
+      variables: { colorPrimary: 'blue' },
+      baseTheme: {
+        __type: 'prebuilt_appearance' as const,
+        cssLayerName: 'theme-layer',
+      },
+    };
+
+    const result = processCssLayerNameExtraction(appearance);
+
+    expect(result?.cssLayerName).toBe('theme-layer');
+    expect(result?.variables?.colorPrimary).toBe('blue');
+    if (result?.baseTheme && !Array.isArray(result.baseTheme)) {
+      expect((result.baseTheme as BaseTheme & { cssLayerName?: string }).cssLayerName).toBeUndefined();
+    }
+  });
+});

packages/clerk-js/src/utils/appearance.ts

@@ -0,0 +1,67 @@
+import type { Appearance, BaseTheme } from '@clerk/types';
+
+/**
+ * Extracts cssLayerName from baseTheme and moves it to appearance level.
+ * This is a pure function that can be tested independently.
+ */
+export function processCssLayerNameExtraction(appearance: Appearance | undefined): Appearance | undefined {
+  if (!appearance || typeof appearance !== 'object' || !('baseTheme' in appearance) || !appearance.baseTheme) {
+    return appearance;
+  }
+
+  let cssLayerNameFromBaseTheme: string | undefined;
+
+  if (Array.isArray(appearance.baseTheme)) {
+    // Handle array of themes - extract cssLayerName from each and use the first one found
+    appearance.baseTheme.forEach((theme: BaseTheme) => {
+      if (!cssLayerNameFromBaseTheme && theme.cssLayerName) {
+        cssLayerNameFromBaseTheme = theme.cssLayerName;
+      }
+    });
+
+    // Create array without cssLayerName properties
+    const processedBaseThemeArray = appearance.baseTheme.map((theme: BaseTheme) => {
+      const { cssLayerName, ...rest } = theme;
+      return rest;
+    });
+
+    // Use existing cssLayerName at appearance level, or fall back to one from baseTheme(s)
+    const finalCssLayerName = appearance.cssLayerName || cssLayerNameFromBaseTheme;
+
+    const result = {
+      ...appearance,
+      baseTheme: processedBaseThemeArray,
+    };
+
+    if (finalCssLayerName) {
+      result.cssLayerName = finalCssLayerName;
+    }
+
+    return result;
+  } else {
+    // Handle single theme
+    const singleTheme = appearance.baseTheme;
+    let cssLayerNameFromSingleTheme: string | undefined;
+
+    if (singleTheme.cssLayerName) {
+      cssLayerNameFromSingleTheme = singleTheme.cssLayerName;
+    }
+
+    // Create new theme without cssLayerName
+    const { cssLayerName, ...processedBaseTheme } = singleTheme;
+
+    // Use existing cssLayerName at appearance level, or fall back to one from baseTheme
+    const finalCssLayerName = appearance.cssLayerName || cssLayerNameFromSingleTheme;
+
+    const result = {
+      ...appearance,
+      baseTheme: processedBaseTheme,
+    };
+
+    if (finalCssLayerName) {
+      result.cssLayerName = finalCssLayerName;
+    }
+
+    return result;
+  }
+}

packages/clerk-js/src/utils/index.ts

@@ -1,4 +1,5 @@
 export * from './beforeUnloadTracker';
+export * from './appearance';
 export * from './commerce';
 export * from './completeSignUpFlow';
 export * from './componentGuards';

packages/themes/src/createTheme.ts

@@ -13,5 +13,8 @@ interface CreateClerkThemeParams extends DeepPartial<Theme> {
 
 export const experimental_createTheme = (appearance: Appearance<CreateClerkThemeParams>): BaseTheme => {
   // Placeholder method that might hande more transformations in the future
-  return { ...appearance, __type: 'prebuilt_appearance' };
+  return {
+    ...appearance,
+    __type: 'prebuilt_appearance',
+  };
 };

packages/themes/src/themes/shadcn.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const shadcn = experimental_createTheme({
+  cssLayerName: 'components',
   variables: {
     colorBackground: 'var(--card)',
     colorDanger: 'var(--destructive)',

packages/types/src/appearance.ts

@@ -806,7 +806,7 @@ export type Variables = {
 };
 
 export type BaseThemeTaggedType = { __type: 'prebuilt_appearance' };
-export type BaseTheme = BaseThemeTaggedType;
+export type BaseTheme = BaseThemeTaggedType & { cssLayerName?: string };
 
 export type Theme = {
   /**