feat(clerk-js): Add support for loading UI styles as first CSS stylesheet

packages/clerk-js/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module '@clerk/ui/styles.css' {
+  const content: string;
+  export default content;
+}

packages/clerk-js/src/ui/new/renderer.tsx

@@ -1,10 +1,8 @@
-// TODO: don't import here
-import '@clerk/ui/styles.css';
-
 import { ClerkInstanceContext, OptionsContext } from '@clerk/shared/react';
 import type { ClerkHostRouter } from '@clerk/shared/router';
 import { ClerkHostRouterContext } from '@clerk/shared/router';
 import type { ClerkOptions, LoadedClerk } from '@clerk/types';
+import stylesheetURL from '@clerk/ui/styles.css';
 import type { ElementType, ReactNode } from 'react';
 import { createElement, lazy } from 'react';
 import { createPortal } from 'react-dom';
@@ -43,6 +41,18 @@ export function init({ wrapper }: { wrapper: ElementType }) {
     rootElement = document.createElement('div');
     rootElement.setAttribute('id', 'clerk-components');
     document.body.appendChild(rootElement);
+
+    // Just for completeness, we check to see if we've already added the stylesheet to the DOM.
+    const STYLESHEET_SIGIL = 'data-clerk-styles';
+    const existingStylesheet = document.querySelector(`link[${STYLESHEET_SIGIL}]`);
+    if (!existingStylesheet) {
+      const stylesheet = document.createElement('link');
+      stylesheet.href = stylesheetURL;
+      stylesheet.rel = 'stylesheet';
+      stylesheet.setAttribute(STYLESHEET_SIGIL, '');
+      // Add as first stylesheet so that application styles take precedence over our styles.
+      document.head.prepend(stylesheet);
+    }
   }
 
   const root = createRoot(rootElement);

packages/clerk-js/webpack.config.js

@@ -106,9 +106,6 @@ const common = ({ mode }) => {
         },
       },
     },
-    experiments: {
-      css: true,
-    },
   };
 };
 
@@ -173,12 +170,21 @@ const typescriptLoaderDev = () => {
   };
 };
 
+/** @type { () => (import('webpack').RuleSetRule) } */
+const clerkUICSSLoader = () => {
+  // This emits a module exporting the URL to the styles.css file.
+  return {
+    test: /packages\/ui\/dist\/styles\.css/,
+    type: 'asset/resource',
+  };
+};
+
 /** @type { () => (import('webpack').Configuration) } */
 const commonForProd = () => {
   return {
     devtool: undefined,
     module: {
-      rules: [svgLoader(), typescriptLoaderProd()],
+      rules: [svgLoader(), typescriptLoaderProd(), clerkUICSSLoader()],
     },
     output: {
       path: path.resolve(__dirname, 'dist'),
@@ -297,7 +303,7 @@ const devConfig = ({ mode, env }) => {
   const commonForDev = () => {
     return {
       module: {
-        rules: [svgLoader(), typescriptLoaderDev()],
+        rules: [svgLoader(), typescriptLoaderDev(), clerkUICSSLoader()],
       },
       plugins: [
         new ReactRefreshWebpackPlugin({ overlay: { sockHost: devUrl.host } }),