vite: Add emitCssInSsr option (#989)

Author: michaeltaranto

.changeset/shy-beers-pull.md

@@ -0,0 +1,21 @@
+---
+'@vanilla-extract/vite-plugin': minor
+---
+
+Add `emitCssInSsr` option
+
+Provides the ability to opt in to emitting CSS during SSR.
+
+```js
+// vite.config.js
+
+import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
+
+export default {
+  plugins: [
+    vanillaExtractPlugin({
+      emitCssInSsr: true
+    })
+  ]
+};
+```

packages/vite-plugin/src/index.ts

@@ -22,18 +22,23 @@ const virtualExtJs = '.vanilla.js';
 
 interface Options {
   identifiers?: IdentifierOption;
+  emitCssInSsr?: boolean;
   esbuildOptions?: CompileOptions['esbuildOptions'];
 }
 export function vanillaExtractPlugin({
   identifiers,
+  emitCssInSsr,
   esbuildOptions,
 }: Options = {}): Plugin {
   let config: ResolvedConfig;
   let server: ViteDevServer;
   let postCssConfig: PostCSSConfigResult | null;
   const cssMap = new Map<string, string>();
 
-  let forceEmitCssInSsrBuild: boolean = !!process.env.VITE_RSC_BUILD;
+  const hasEmitCssOverride = typeof emitCssInSsr === 'boolean';
+  let resolvedEmitCssInSsr: boolean = hasEmitCssOverride
+    ? emitCssInSsr
+    : !!process.env.VITE_RSC_BUILD;
   let packageName: string;
 
   const getAbsoluteVirtualFileId = (source: string) =>
@@ -69,6 +74,7 @@ export function vanillaExtractPlugin({
       }
 
       if (
+        !hasEmitCssOverride &&
         config.plugins.some((plugin) =>
           [
             'astro:build',
@@ -78,7 +84,7 @@ export function vanillaExtractPlugin({
           ].includes(plugin.name),
         )
       ) {
-        forceEmitCssInSsrBuild = true;
+        resolvedEmitCssInSsr = true;
       }
     },
     resolveId(source) {
@@ -153,7 +159,7 @@ export function vanillaExtractPlugin({
         ssr = ssrParam?.ssr;
       }
 
-      if (ssr && !forceEmitCssInSsrBuild) {
+      if (ssr && !resolvedEmitCssInSsr) {
         return transform({
           source: code,
           filePath: normalizePath(validId),
@@ -184,7 +190,7 @@ export function vanillaExtractPlugin({
         identOption,
         serializeVirtualCssPath: async ({ fileScope, source }) => {
           const rootRelativeId = `${fileScope.filePath}${
-            config.command === 'build' || (ssr && forceEmitCssInSsrBuild)
+            config.command === 'build' || (ssr && resolvedEmitCssInSsr)
               ? virtualExtCss
               : virtualExtJs
           }`;

site/docs/integrations/vite.md

@@ -53,3 +53,26 @@ Different formatting of identifiers (e.g. class names, keyframes, CSS Vars, etc)
 - `debug` identifiers contain human readable prefixes representing the owning filename and a potential rule level debug name. e.g. `myfile_mystyle_hnw5tz3`
 
 Each integration will set a default value based on the configuration options passed to the bundler.
+
+### emitCssInSsr
+
+Historically, extracting CSS was a side effect of building the browser bundle, with the server or static build process only needing the JavaScript references. However, many frameworks are now moving the evaluation of CSS to be a server-side or compile-time responsibility.
+
+For the most common frameworks, Vanilla Extract will set this flag internally based on the plugins it discovers in the consumers Vite configuration.
+This makes the plugin essentially zero config for the majority of cases.
+
+For other cases, such as newer frameworks, it may be necessary to manually opt in to emitting CSS during server side rendering:
+
+```js
+// vite.config.js
+
+import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
+
+export default {
+  plugins: [
+    vanillaExtractPlugin({
+      emitCssInSsr: true
+    })
+  ]
+};
+```