From 90a57a81e113a5ae496c489bb58797623603c15e Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 7 Apr 2025 16:44:08 -0400
Subject: [PATCH 1/7] feat(clerk-js,types): Add experimental css layer name
 option

---
 packages/clerk-js/sandbox/app.ts              |  2 +-
 .../clerk-js/src/ui/lazyModules/providers.tsx |  5 +++-
 .../ui/styledSystem/StyleCacheProvider.tsx    | 24 ++++++++++++++++++-
 packages/types/src/clerk.ts                   |  4 ++++
 4 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/packages/clerk-js/sandbox/app.ts b/packages/clerk-js/sandbox/app.ts
index a3571e9508c..a16ef4fc051 100644
--- a/packages/clerk-js/sandbox/app.ts
+++ b/packages/clerk-js/sandbox/app.ts
@@ -326,7 +326,7 @@ void (async () => {
       ...(componentControls.clerk.getProps() ?? {}),
       signInUrl: '/sign-in',
       signUpUrl: '/sign-up',
-      experimental: { commerce: true },
+      experimental: { commerce: true, cssLayerName: 'clerk' },
     });
     renderCurrentRoute();
     updateVariables();
diff --git a/packages/clerk-js/src/ui/lazyModules/providers.tsx b/packages/clerk-js/src/ui/lazyModules/providers.tsx
index 223c9fba029..6843a304277 100644
--- a/packages/clerk-js/src/ui/lazyModules/providers.tsx
+++ b/packages/clerk-js/src/ui/lazyModules/providers.tsx
@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
   return (
-    <StyleCacheProvider nonce={props.options.nonce}>
+    <StyleCacheProvider
+      nonce={props.options.nonce}
+      cssLayerName={props.options.experimental?.cssLayerName}
+    >
       <CoreClerkContextWrapper clerk={props.clerk}>
         <EnvironmentProvider value={props.environment}>
           <OptionsProvider value={props.options}>{props.children}</OptionsProvider>
diff --git a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
index 37564095c9f..ed66b0649d2 100644
--- a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
+++ b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
@@ -1,13 +1,34 @@
 // eslint-disable-next-line no-restricted-imports
+import type { StylisPlugin } from '@emotion/cache';
+// eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
 import { CacheProvider } from '@emotion/react';
 import React, { useMemo } from 'react';
 
+const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
+  // if we're not at the root of a <style> tag, leave the tree intact
+  if (node.parent) return;
+
+  // if we're at the root, replace node with `@layer layerName { node }`
+  const child = { ...node, parent: node, root: node };
+  Object.assign(node, {
+    children: [child],
+    length: 6,
+    parent: null,
+    props: [layerName],
+    return: '',
+    root: null,
+    type: '@layer',
+    value: `@layer ${layerName}`,
+  });
+};
+
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
   nonce?: string;
+  cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
@@ -18,8 +39,9 @@ export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
         prepend: !el,
         insertionPoint: el ? (el as HTMLElement) : undefined,
         nonce: props.nonce,
+        stylisPlugins: props.cssLayerName ? [wrapInLayer(props.cssLayerName)] : undefined,
       }),
-    [props.nonce],
+    [props.nonce, props.cssLayerName],
   );
 
   return <CacheProvider value={cache}>{props.children}</CacheProvider>;
diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts
index 444f5f40853..2e71e895afa 100644
--- a/packages/types/src/clerk.ts
+++ b/packages/types/src/clerk.ts
@@ -839,6 +839,10 @@ export type ClerkOptions = PendingSessionOptions &
          */
         rethrowOfflineNetworkErrors: boolean;
         commerce: boolean;
+        /**
+         * The name of the CSS layer to use for Clerk components.
+         */
+        cssLayerName?: string;
       },
       Record<string, any>
     >;

From 5cdfd5353b4f6a0913825441f9b0a4673afb0838 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 7 Apr 2025 16:44:52 -0400
Subject: [PATCH 2/7] Update app.ts

---
 packages/clerk-js/sandbox/app.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/clerk-js/sandbox/app.ts b/packages/clerk-js/sandbox/app.ts
index a16ef4fc051..a3571e9508c 100644
--- a/packages/clerk-js/sandbox/app.ts
+++ b/packages/clerk-js/sandbox/app.ts
@@ -326,7 +326,7 @@ void (async () => {
       ...(componentControls.clerk.getProps() ?? {}),
       signInUrl: '/sign-in',
       signUpUrl: '/sign-up',
-      experimental: { commerce: true, cssLayerName: 'clerk' },
+      experimental: { commerce: true },
     });
     renderCurrentRoute();
     updateVariables();

From 52e311c82511bf6240abd7df55be786554e01eaf Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 7 Apr 2025 16:49:24 -0400
Subject: [PATCH 3/7] add changeset

---
 .changeset/metal-phones-like.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .changeset/metal-phones-like.md

diff --git a/.changeset/metal-phones-like.md b/.changeset/metal-phones-like.md
new file mode 100644
index 00000000000..ed0c66b994c
--- /dev/null
+++ b/.changeset/metal-phones-like.md
@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Introduce experimental `cssLayerName` option to allow users to opt into CSS layers.

From 07a90cbfc85f387f9582429bbf0122f288deb99e Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 7 Apr 2025 17:58:04 -0400
Subject: [PATCH 4/7] getInsertionPoint

---
 .../src/ui/styledSystem/StyleCacheProvider.tsx       | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
index ed66b0649d2..a464fa4dfdc 100644
--- a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
+++ b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
@@ -24,7 +24,15 @@ const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
   });
 };
 
-const el = document.querySelector('style#cl-style-insertion-point');
+const getInsertionPoint = () => {
+  const metaTag = document.querySelector('meta[name="emotion-insertion-point"]');
+  if (metaTag) {
+    return metaTag as HTMLElement;
+  }
+  return document.querySelector('style#cl-style-insertion-point') as HTMLElement;
+};
+
+const el = getInsertionPoint();
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
   nonce?: string;
@@ -37,7 +45,7 @@ export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
       createCache({
         key: 'cl-internal',
         prepend: !el,
-        insertionPoint: el ? (el as HTMLElement) : undefined,
+        insertionPoint: el ? el : undefined,
         nonce: props.nonce,
         stylisPlugins: props.cssLayerName ? [wrapInLayer(props.cssLayerName)] : undefined,
       }),

From ffa35fefe32c8e2b72b8fe5faf7575de835d7b80 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 8 Apr 2025 08:58:47 -0400
Subject: [PATCH 5/7] document

---
 .../ui/styledSystem/StyleCacheProvider.tsx    | 47 ++++++++++++++-----
 1 file changed, 36 insertions(+), 11 deletions(-)

diff --git a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
index a464fa4dfdc..d0b978258d5 100644
--- a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
+++ b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
@@ -4,8 +4,13 @@ import type { StylisPlugin } from '@emotion/cache';
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
 import { CacheProvider } from '@emotion/react';
-import React, { useMemo } from 'react';
+import React, { useEffect, useMemo, useState } from 'react';
 
+/**
+ * A Stylis plugin that wraps CSS rules in a CSS layer
+ * @param layerName - The name of the CSS layer to wrap the styles in
+ * @returns A Stylis plugin function
+ */
 const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
   // if we're not at the root of a <style> tag, leave the tree intact
   if (node.parent) return;
@@ -24,32 +29,52 @@ const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
   });
 };
 
-const getInsertionPoint = () => {
-  const metaTag = document.querySelector('meta[name="emotion-insertion-point"]');
-  if (metaTag) {
-    return metaTag as HTMLElement;
+/**
+ * Finds the appropriate insertion point for Emotion styles in the DOM
+ * @returns The HTMLElement to use as insertion point, or undefined if none found
+ */
+const getInsertionPoint = (): HTMLElement | undefined => {
+  try {
+    const metaTag = document.querySelector('meta[name="emotion-insertion-point"]');
+    if (metaTag) {
+      return metaTag as HTMLElement;
+    }
+    return document.querySelector('style#cl-style-insertion-point') as HTMLElement;
+  } catch (error) {
+    console.warn('Failed to find Emotion insertion point:', error);
+    return undefined;
   }
-  return document.querySelector('style#cl-style-insertion-point') as HTMLElement;
 };
 
-const el = getInsertionPoint();
-
 type StyleCacheProviderProps = React.PropsWithChildren<{
+  /** Optional nonce value for CSP (Content Security Policy) */
   nonce?: string;
+  /** Optional CSS layer name to wrap styles in */
   cssLayerName?: string;
 }>;
 
+/**
+ * Provides an Emotion cache configuration for styling with support for CSS layers and CSP nonce
+ * @param props - Component props
+ * @returns A CacheProvider component with configured Emotion cache
+ */
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
+  const [insertionPoint, setInsertionPoint] = useState<HTMLElement | undefined>();
+
+  useEffect(() => {
+    setInsertionPoint(getInsertionPoint());
+  }, []);
+
   const cache = useMemo(
     () =>
       createCache({
         key: 'cl-internal',
-        prepend: !el,
-        insertionPoint: el ? el : undefined,
+        prepend: !insertionPoint,
+        insertionPoint: insertionPoint ?? undefined,
         nonce: props.nonce,
         stylisPlugins: props.cssLayerName ? [wrapInLayer(props.cssLayerName)] : undefined,
       }),
-    [props.nonce, props.cssLayerName],
+    [props.nonce, props.cssLayerName, insertionPoint],
   );
 
   return <CacheProvider value={cache}>{props.children}</CacheProvider>;

From 1e594b700bcc5d8c75c9fd165bb4c22550f55381 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 8 Apr 2025 08:59:31 -0400
Subject: [PATCH 6/7] document

---
 packages/types/src/clerk.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts
index 2e71e895afa..012ac7b50cb 100644
--- a/packages/types/src/clerk.ts
+++ b/packages/types/src/clerk.ts
@@ -841,6 +841,18 @@ export type ClerkOptions = PendingSessionOptions &
         commerce: boolean;
         /**
          * The name of the CSS layer to use for Clerk components.
+         * @example
+         * ```tsx
+         * <ClerkProvider cssLayerName="components">
+         *   <App />
+         * </ClerkProvider>
+         * ```
+         * This will wrap all Clerk styles in a `components` CSS layer to work with tools like Tailwind CSS V4.
+         *```css
+         * @layer components {
+         *   ... clerk styles ...
+         * }
+         *```
          */
         cssLayerName?: string;
       },

From 2c23dbfc4a884b1c6dcb198c6415b6b81b2501c4 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 8 Apr 2025 09:34:09 -0400
Subject: [PATCH 7/7] add tests

---
 .../ui/styledSystem/StyleCacheProvider.tsx    |  4 +-
 .../__tests__/StyleCacheProvider.test.tsx     | 96 +++++++++++++++++++
 2 files changed, 98 insertions(+), 2 deletions(-)
 create mode 100644 packages/clerk-js/src/ui/styledSystem/__tests__/StyleCacheProvider.test.tsx

diff --git a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
index d0b978258d5..55d663be8fd 100644
--- a/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
+++ b/packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx
@@ -11,7 +11,7 @@ import React, { useEffect, useMemo, useState } from 'react';
  * @param layerName - The name of the CSS layer to wrap the styles in
  * @returns A Stylis plugin function
  */
-const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
+export const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
   // if we're not at the root of a <style> tag, leave the tree intact
   if (node.parent) return;
 
@@ -33,7 +33,7 @@ const wrapInLayer: (layerName: string) => StylisPlugin = layerName => node => {
  * Finds the appropriate insertion point for Emotion styles in the DOM
  * @returns The HTMLElement to use as insertion point, or undefined if none found
  */
-const getInsertionPoint = (): HTMLElement | undefined => {
+export const getInsertionPoint = (): HTMLElement | undefined => {
   try {
     const metaTag = document.querySelector('meta[name="emotion-insertion-point"]');
     if (metaTag) {
diff --git a/packages/clerk-js/src/ui/styledSystem/__tests__/StyleCacheProvider.test.tsx b/packages/clerk-js/src/ui/styledSystem/__tests__/StyleCacheProvider.test.tsx
new file mode 100644
index 00000000000..62535a43016
--- /dev/null
+++ b/packages/clerk-js/src/ui/styledSystem/__tests__/StyleCacheProvider.test.tsx
@@ -0,0 +1,96 @@
+// eslint-disable-next-line no-restricted-imports
+import type { StylisElement } from '@emotion/cache';
+
+import { getInsertionPoint, wrapInLayer } from '../StyleCacheProvider';
+
+// Mock the StylisPlugin type
+type MockStylisElement = Partial<StylisElement> & {
+  type: string;
+  props: string[];
+  children: MockStylisElement[];
+  parent: MockStylisElement | null;
+  root: MockStylisElement | null;
+  length: number;
+  value: string;
+  return: string;
+  line: number;
+  column: number;
+};
+
+describe('wrapInLayer', () => {
+  it('wraps CSS rules in a CSS layer', () => {
+    const node: MockStylisElement = {
+      type: 'rule',
+      props: ['body'],
+      children: [],
+      parent: null,
+      root: null,
+      length: 0,
+      value: '',
+      return: '',
+      line: 1,
+      column: 1,
+    };
+
+    const plugin = wrapInLayer('test-layer');
+    // @ts-expect-error - We're mocking the StylisPlugin type
+    plugin(node);
+
+    expect(node.type).toBe('@layer');
+    expect(node.props).toEqual(['test-layer']);
+    expect(node.children).toHaveLength(1);
+    const child = node.children[0];
+    expect(child.props).toEqual(['body']);
+  });
+
+  it('does not wrap if node has a parent', () => {
+    const node: MockStylisElement = {
+      type: 'rule',
+      props: ['body'],
+      children: [],
+      parent: { type: 'parent' } as MockStylisElement,
+      root: null,
+      length: 0,
+      value: '',
+      return: '',
+      line: 1,
+      column: 1,
+    };
+
+    const originalNode = { ...node };
+    const plugin = wrapInLayer('test-layer');
+    // @ts-expect-error - We're mocking the StylisPlugin type
+    plugin(node);
+
+    expect(node).toEqual(originalNode);
+  });
+});
+
+describe('getInsertionPoint', () => {
+  beforeEach(() => {
+    document.head.innerHTML = '';
+  });
+
+  it('returns meta tag if found', () => {
+    const meta = document.createElement('meta');
+    meta.setAttribute('name', 'emotion-insertion-point');
+    document.head.appendChild(meta);
+
+    const result = getInsertionPoint();
+    expect(result).toBe(meta);
+  });
+
+  it('returns style tag if found', () => {
+    const style = document.createElement('style');
+    style.id = 'cl-style-insertion-point';
+    document.head.appendChild(style);
+
+    const result = getInsertionPoint();
+    expect(result).toBe(style);
+  });
+
+  it('returns null if no insertion point found', () => {
+    const result = getInsertionPoint();
+    expect(result).toBeNull();
+  });
+});