feat(clerk-js,themes,shared): Add theme-usage telemetry

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });

.changeset/orange-tips-turn.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/themes': patch
+---
+
+Add theme-usage telemetry

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "819KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -10,6 +10,7 @@ import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/sh
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
+ eventThemeUsage,
  TelemetryCollector,
 } from '@clerk/shared/telemetry';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
@@ -462,6 +463,11 @@ export class Clerk implements ClerkInterface {
  publishableKey: this.publishableKey,
  ...this.#options.telemetry,
  });
+
+ // Record theme usage telemetry when appearance is provided
+ if (this.#options.appearance) {
+ this.telemetry.record(eventThemeUsage(this.#options.appearance));
+ }
  }
 
  try {

packages/shared/src/telemetry/events/__tests__/theme-usage.test.ts

@@ -0,0 +1,127 @@
+import { EVENT_SAMPLING_RATE, EVENT_THEME_USAGE, eventThemeUsage } from '../theme-usage';
+
+describe('eventThemeUsage', () => {
+ it('should create telemetry event with shadcn theme name', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ variables: { colorPrimary: 'var(--primary)' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle string themes', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle array of themes', () => {
+ const appearance = {
+ theme: [
+ 'clerk' as any, // String themes are valid at runtime
+ {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ ] as any,
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should handle themes without explicit names', () => {
+ const appearance = {
+ theme: {
+ __type: 'prebuilt_appearance' as const,
+ variables: { colorPrimary: 'blue' },
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: undefined },
+ });
+ });
+
+ it('should prioritize theme over deprecated baseTheme', () => {
+ const appearance = {
+ theme: 'clerk' as any, // String themes are valid at runtime
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'clerk' },
+ });
+ });
+
+ it('should use baseTheme when theme is not provided', () => {
+ const appearance = {
+ baseTheme: {
+ __type: 'prebuilt_appearance' as const,
+ name: 'shadcn',
+ },
+ };
+
+ const result = eventThemeUsage(appearance);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: { themeName: 'shadcn' },
+ });
+ });
+
+ it('should handle undefined appearance', () => {
+ const result = eventThemeUsage();
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+
+ it('should handle null appearance', () => {
+ const result = eventThemeUsage(null as any);
+
+ expect(result).toEqual({
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload: {},
+ });
+ });
+});

packages/shared/src/telemetry/events/index.ts

@@ -1,3 +1,4 @@
 export * from './component-mounted';
 export * from './method-called';
 export * from './framework-metadata';
+export * from './theme-usage';

packages/shared/src/telemetry/events/theme-usage.ts

@@ -0,0 +1,83 @@
+import type { Appearance, BaseTheme, TelemetryEventRaw } from '@clerk/types';
+
+export const EVENT_THEME_USAGE = 'THEME_USAGE';
+export const EVENT_SAMPLING_RATE = 1;
+
+type EventThemeUsage = {
+ /**
+ * The name of the theme being used (e.g., "shadcn", "neobrutalism", etc.).
+ */
+ themeName?: string;
+};
+
+/**
+ * Helper function for `telemetry.record()`. Create a consistent event object for tracking theme usage in ClerkProvider.
+ *
+ * @param appearance - The appearance prop from ClerkProvider.
+ * @example
+ * telemetry.record(eventThemeUsage(appearance));
+ */
+export function eventThemeUsage(appearance?: Appearance): TelemetryEventRaw<EventThemeUsage> {
+ const payload = analyzeThemeUsage(appearance);
+
+ return {
+ event: EVENT_THEME_USAGE,
+ eventSamplingRate: EVENT_SAMPLING_RATE,
+ payload,
+ };
+}
+
+/**
+ * Analyzes the appearance prop to extract theme usage information for telemetry.
+ *
+ * @internal
+ */
+function analyzeThemeUsage(appearance?: Appearance): EventThemeUsage {
+ if (!appearance || typeof appearance !== 'object') {
+ return {};
+ }
+
+ // Prioritize the new theme property over deprecated baseTheme
+ const themeProperty = appearance.theme || appearance.baseTheme;
+
+ if (!themeProperty) {
+ return {};
+ }
+
+ let themeName: string | undefined;
+
+ if (Array.isArray(themeProperty)) {
+ // Look for the first identifiable theme name in the array
+ for (const theme of themeProperty) {
+ const name = extractThemeName(theme);
+ if (name) {
+ themeName = name;
+ break;
+ }
+ }
+ } else {
+ themeName = extractThemeName(themeProperty);
+ }
+
+ return { themeName };
+}
+
+/**
+ * Extracts the theme name from a theme object.
+ *
+ * @internal
+ */
+function extractThemeName(theme: BaseTheme): string | undefined {
+ if (typeof theme === 'string') {
+ return theme;
+ }
+
+ if (typeof theme === 'object' && theme !== null) {
+ // Check for explicit theme name
+ if ('name' in theme && typeof theme.name === 'string') {
+ return theme.name;
+ }
+ }
+
+ return undefined;
+}

packages/themes/src/createTheme.ts

@@ -5,6 +5,12 @@ import type { Appearance, BaseTheme, DeepPartial, Elements, Theme } from '@clerk
 import type { InternalTheme } from '../../clerk-js/src/ui/foundations';
 
 interface CreateClerkThemeParams extends DeepPartial<Theme> {
+ /**
+ * Optional name for the theme, used for telemetry and debugging.
+ * @example 'shadcn', 'neobrutalism', 'custom-dark'
+ */
+ name?: string;
+
  /**
  * {@link Theme.elements}
  */

packages/themes/src/themes/dark.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const dark = experimental_createTheme({
+ name: 'dark',
  variables: {
  colorBackground: '#212126',
  colorNeutral: 'white',

packages/themes/src/themes/neobrutalism.ts

@@ -20,6 +20,7 @@ const shadowStyle = {
 };
 
 export const neobrutalism = experimental_createTheme({
+ name: 'neobrutalism',
  //@ts-expect-error not public api
  simpleStyles: true,
  variables: {

packages/themes/src/themes/shadcn.ts

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

packages/themes/src/themes/shadesOfPurple.ts

@@ -2,6 +2,7 @@ import { experimental_createTheme } from '../createTheme';
 import { dark } from './dark';
 
 export const shadesOfPurple = experimental_createTheme({
+ name: 'shadesOfPurple',
  baseTheme: dark,
  variables: {
  colorBackground: '#3f3c77',

packages/themes/src/themes/simple.ts

@@ -1,6 +1,7 @@
 import { experimental_createTheme } from '../createTheme';
 
 export const experimental__simple = experimental_createTheme({
+ name: 'simple',
  //@ts-expect-error not public api
  simpleStyles: true,
 });