Add disableRuntimeStyles entrypoint (#206)

Author: mattcompiles

.changeset/pink-impalas-prove.md

@@ -0,0 +1,13 @@
+---
+'@vanilla-extract/css': minor
+---
+
+Add `disableRuntimeStyles` entrypoint
+
+In testing environments (like `jsdom`) vanilla-extract will create and insert styles. While this is often desirable, it can be a major slowdown in your tests. If your tests don't require styles to be available, the `disableRuntimeStyles` import will disable all style creation.
+
+```ts
+// setupTests.ts
+import '@vanilla-extract/css/disableRuntimeStyles';
+```
+

README.md

@@ -84,6 +84,7 @@ Want to work at a higher level while maximising style re-use? Check out  🍨 [S
   - [Vite](#vite)
   - [Snowpack](#snowpack)
   - [Gatsby](#gatsby)
+  - [Test environments](#test-environments)
 - [Styling API](#styling-api)
   - [style](#style)
   - [styleVariants](#styleVariants)
@@ -282,6 +283,32 @@ $ npm install @vanilla-extract/css @vanilla-extract/snowpack-plugin
 
 To add to your [Gatsby](https://www.gatsbyjs.com) site, use the [gatsby-plugin-vanilla-extract](https://github.com/KyleAMathews/gatsby-plugin-vanilla-extract) plugin.
 
+### Test environments
+
+1. Install the dependencies.
+
+```bash
+$ npm install @vanilla-extract/babel-plugin
+```
+
+2. Add the [Babel](https://babeljs.io) plugin.
+
+```json
+{
+  "plugins": ["@vanilla-extract/babel-plugin"]
+}
+```
+
+3. Disable runtime styles (Optional)
+
+In testing environments (like `jsdom`) vanilla-extract will create and insert styles. While this is often desirable, it can be a major slowdown in your tests. If your tests don’t require styles to be available, the `disableRuntimeStyles` import will disable all style creation.
+
+```ts
+// setupTests.ts
+import '@vanilla-extract/css/disableRuntimeStyles';
+```
+
+
 ---
 
 ## Styling API

packages/css/disableRuntimeStyles/package.json

@@ -0,0 +1,8 @@
+{
+  "main": "dist/vanilla-extract-css-disableRuntimeStyles.cjs.js",
+  "module": "dist/vanilla-extract-css-disableRuntimeStyles.esm.js",
+  "browser": {
+    "./dist/vanilla-extract-css-disableRuntimeStyles.cjs.js": "./dist/vanilla-extract-css-disableRuntimeStyles.browser.cjs.js",
+    "./dist/vanilla-extract-css-disableRuntimeStyles.esm.js": "./dist/vanilla-extract-css-disableRuntimeStyles.browser.esm.js"
+  }
+}

packages/css/package.json

@@ -15,15 +15,17 @@
       "recipe.ts",
       "adapter.ts",
       "transformCss.ts",
-      "fileScope.ts"
+      "fileScope.ts",
+      "disableRuntimeStyles.ts"
     ]
   },
   "files": [
     "/dist",
     "/recipe",
     "/adapter",
     "/transformCss",
-    "/fileScope"
+    "/fileScope",
+    "/disableRuntimeStyles"
   ],
   "repository": {
     "type": "git",

packages/css/src/adapter.ts

@@ -1,12 +1,23 @@
 import type { Adapter } from './types';
 
-let adapter: Adapter = {
+export const mockAdapter: Adapter = {
   appendCss: () => {},
   registerClassName: () => {},
   onEndFileScope: () => {},
 };
 
+let adapter: Adapter = mockAdapter;
+
+let hasConfiguredAdapter = false;
+
+export const setAdapterIfNotSet = (newAdapter: Adapter) => {
+  if (!hasConfiguredAdapter) {
+    setAdapter(newAdapter);
+  }
+};
+
 export const setAdapter = (newAdapter: Adapter) => {
+  hasConfiguredAdapter = true;
   adapter = newAdapter;
 };
 

packages/css/src/disableRuntimeStyles.ts

@@ -0,0 +1,3 @@
+import { setAdapter, mockAdapter } from './adapter';
+
+setAdapter(mockAdapter);

packages/css/src/runtimeAdapter.ts

@@ -1,6 +1,6 @@
 import type { Adapter, CSS, FileScope } from './types';
 import { transformCss } from './transformCss';
-import { setAdapter } from './adapter';
+import { setAdapterIfNotSet } from './adapter';
 
 const stylesheets: Record<string, CSSStyleSheet> = {};
 
@@ -64,5 +64,5 @@ const browserRuntimeAdapter: Adapter = {
 };
 
 if (typeof window !== 'undefined') {
-  setAdapter(browserRuntimeAdapter);
+  setAdapterIfNotSet(browserRuntimeAdapter);
 }

site/docs/setup.md

@@ -187,3 +187,28 @@ $ npm install @vanilla-extract/css @vanilla-extract/snowpack-plugin
 ## Gatsby
 
 To add to your [Gatsby](https://www.gatsbyjs.com) site, use the [gatsby-plugin-vanilla-extract](https://github.com/KyleAMathews/gatsby-plugin-vanilla-extract) plugin.
+
+## Test environments
+
+1/ Install the dependencies.
+
+```bash
+$ npm install @vanilla-extract/babel-plugin
+```
+
+2/ Add the [Babel](https://babeljs.io) plugin.
+
+```json
+{
+  "plugins": ["@vanilla-extract/babel-plugin"]
+}
+```
+
+3/ Disable runtime styles (Optional)
+
+In testing environments (like `jsdom`) vanilla-extract will create and insert styles. While this is often desirable, it can be a major slowdown in your tests. If your tests don’t require styles to be available, the `disableRuntimeStyles` import will disable all style creation.
+
+```ts
+// setupTests.ts
+import '@vanilla-extract/css/disableRuntimeStyles';
+```