esbuild-plugin: Document processCss option (#185)

Co-authored-by: Michael Taranto <[email protected]>

Author: mattcompiles

.changeset/curly-bats-allow.md

@@ -7,22 +7,28 @@ Add `processCss` plugin option to allow further processing of CSS while bundling
 **Example for postcss with autoprefixer:**
 
 ```js
-const { vanillaExtractPlugin } = require('@vanilla-extract/esbuild-plugin');
-const postcss = require('postcss');
-const autoprefixer = require('autoprefixer');
+const { vanillaExtractPlugin } = require("@vanilla-extract/esbuild-plugin");
+const postcss = require("postcss");
+const autoprefixer = require("autoprefixer");
 
-require('esbuild').build({
-  entryPoints: ['app.ts'],
-  bundle: true,
-  plugins: [vanillaExtractPlugin({
+async function processCss(css) {
+  const result = await postcss([autoprefixer]).process(css, {
+      from: undefined /* suppress source map warning */,
+  });
 
-    processCss: async (css) => {
-      return (await postcss([autoprefixer])
-        .process(css, { from: undefined /* suppress source map warning */ })
-      ).css
-    }
+  return result.css;
+}
 
-  })],
-  outfile: 'out.js',
-}).catch(() => process.exit(1))
+require("esbuild")
+  .build({
+    entryPoints: ["app.ts"],
+    bundle: true,
+    plugins: [
+      vanillaExtractPlugin({
+        processCss,
+      }),
+    ],
+    outfile: "out.js",
+  })
+  .catch(() => process.exit(1));
 ```

README.md

@@ -193,6 +193,44 @@ require('esbuild').build({
 
 > Please note: There are currently no automatic readable class names during development. However, you can still manually provide a debug ID as the last argument to functions that generate scoped styles, e.g. `export const className = style({ ... }, 'className');`
 
+3. Process CSS
+
+As [esbuild](https://esbuild.github.io/) currently doesn't have a way to process the CSS generated by vanilla-extract, you can optionally use the `processCss` option.
+
+For example, to run autoprefixer over the generated CSS.
+
+```js
+const {
+  vanillaExtractPlugin
+} = require('@vanilla-extract/esbuild-plugin');
+const postcss = require('postcss');
+const autoprefixer = require('autoprefixer');
+
+async function processCss(css) {
+  const result = await postcss([autoprefixer]).process(
+    css,
+    {
+      from: undefined /* suppress source map warning */
+    }
+  );
+
+  return result.css;
+}
+
+require('esbuild')
+  .build({
+    entryPoints: ['app.ts'],
+    bundle: true,
+    plugins: [
+      vanillaExtractPlugin({
+        processCss
+      })
+    ],
+    outfile: 'out.js'
+  })
+  .catch(() => process.exit(1));
+```
+
 ### Vite
 
 > Warning: Currently the Vite plugin doesn't rebuild files when dependent files change, e.g. updating `theme.css.ts` should rebuild `styles.css.ts` which imports `theme.css.ts`. This is a limitation in the Vite Plugin API that will hopefully be resolved soon. You can track the Vite issue here: https://github.com/vitejs/vite/issues/3216
@@ -216,15 +254,15 @@ export default {
 
 > Please note: There are currently no automatic readable class names during development. However, you can still manually provide a debug ID as the last argument to functions that generate scoped styles, e.g. `export const className = style({ ... }, 'className');`
 
-## Snowpack
+### Snowpack
 
-1/ Install the dependencies.
+1. Install the dependencies.
 
 ```bash
 $ npm install @vanilla-extract/css @vanilla-extract/snowpack-plugin
 ```
 
-2/ Add the [Snowpack](https://www.snowpack.dev/) plugin to your snowpack config.
+2. Add the [Snowpack](https://www.snowpack.dev/) plugin to your snowpack config.
 
 ```js
 // snowpack.config.json

site/docs/setup.md

@@ -93,6 +93,46 @@ require('esbuild')
 
 > Please note: There are currently no automatic readable class names during development. However, you can still manually provide a debug ID as the last argument to functions that generate scoped styles, e.g. `export const className = style({ ... }, 'className');`
 
+3/ Process CSS
+
+As [esbuild](https://esbuild.github.io/) currently doesn't have a way to process the CSS generated by vanilla-extract, you can optionally use the `processCss` option.
+
+For example, to run autoprefixer over the generated CSS.
+
+```js
+// bundle.js
+
+const {
+  vanillaExtractPlugin
+} = require('@vanilla-extract/esbuild-plugin');
+const postcss = require('postcss');
+const autoprefixer = require('autoprefixer');
+
+async function processCss(css) {
+  const result = await postcss([autoprefixer]).process(
+    css,
+    {
+      from: undefined /* suppress source map warning */
+    }
+  );
+
+  return result.css;
+}
+
+require('esbuild')
+  .build({
+    entryPoints: ['app.ts'],
+    bundle: true,
+    plugins: [
+      vanillaExtractPlugin({
+        processCss
+      })
+    ],
+    outfile: 'out.js'
+  })
+  .catch(() => process.exit(1));
+```
+
 ## Vite
 
 > Warning: Currently the Vite plugin doesn't rebuild files when dependent files change, e.g. updating `theme.css.ts` should rebuild `styles.css.ts` which imports `theme.css.ts`. This is a [limitation in the Vite Plugin API](https://github.com/vitejs/vite/issues/3216) that will hopefully be resolved soon.