Setup

There are currently a few integrations to choose from.

1/ Install the dependencies.

$ npm install @vanilla-extract/css @vanilla-extract/webpack-plugin

2/ Add the webpack plugin.

💡 This plugin accepts an optional configuration object.

webpack.config.js
const { VanillaExtractPlugin } = require('@vanilla-extract/webpack-plugin'); module.exports = { plugins: [new VanillaExtractPlugin()] };

3/ If you’d like automatic debuggable identifiers, you can add the Babel plugin.

$ npm install @vanilla-extract/babel-plugin
{ "plugins": ["@vanilla-extract/babel-plugin"] }

You’ll need to ensure you’re handling CSS files in your webpack config.

For example:

webpack.config.js
const { VanillaExtractPlugin } = require('@vanilla-extract/webpack-plugin'); const MiniCssExtractPlugin = require('mini-css-extract-plugin'); module.exports = { plugins: [ new VanillaExtractPlugin(), new MiniCssExtractPlugin() ], module: { rules: [ { test: /\.vanilla\.css$/i, // Targets only CSS files generated by vanilla-extract use: [ MiniCssExtractPlugin.loader, { loader: require.resolve('css-loader'), options: { url: false // Required as image imports should be handled via JS/TS import statements } } ] } ] } };

1/ Install the dependencies.

$ npm install @vanilla-extract/css @vanilla-extract/esbuild-plugin

2/ Add the esbuild plugin to your build script.

💡 This plugin accepts an optional configuration object.

bundle.js
const { vanillaExtractPlugin } = require('@vanilla-extract/esbuild-plugin'); require('esbuild') .build({ entryPoints: ['app.ts'], bundle: true, plugins: [vanillaExtractPlugin()], outfile: 'out.js' }) .catch(() => process.exit(1));

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 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.

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));

1/ Install the dependencies.

$ npm install @vanilla-extract/css @vanilla-extract/vite-plugin

2/ Add the Vite plugin to your Vite config.

💡 This plugin accepts an optional configuration object.

vite.config.js
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin'; export default { plugins: [vanillaExtractPlugin()] };

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');

1/ Install the dependencies.

$ npm install @vanilla-extract/css @vanilla-extract/snowpack-plugin

2/ Add the Snowpack plugin to your snowpack config.

💡 This plugin accepts an optional configuration object.

snowpack.config.json
{ "plugins": ["@vanilla-extract/snowpack-plugin"] }

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');

1/ Install the dependencies.

npm install @vanilla-extract/css @vanilla-extract/babel-plugin @vanilla-extract/next-plugin

2/ If you don’t have a .babelrc file in the root of your project, create one. Add the Babel plugin to your .babelrc file, ensuring that you’re also including "next/babel" in your presets array.

{ "presets": ["next/babel"], "plugins": ["@vanilla-extract/babel-plugin"] }

3/ If you don’t have a next.config.js file in the root of your project, create one. Add the Next.js plugin to your next.config.js file.

💡 This plugin accepts an optional configuration object.

const { createVanillaExtractPlugin } = require('@vanilla-extract/next-plugin'); const withVanillaExtract = createVanillaExtractPlugin(); const nextConfig = {}; module.exports = withVanillaExtract(nextConfig);

If required, this plugin can be composed with other plugins.

const { createVanillaExtractPlugin } = require('@vanilla-extract/next-plugin'); const withVanillaExtract = createVanillaExtractPlugin(); const withMDX = require('@next/mdx')({ extension: /\.mdx$/ }); const nextConfig = {}; module.exports = withVanillaExtract(withMDX(nextConfig));

To add to your Gatsby site, use the gatsby-plugin-vanilla-extract plugin.

1/ Install the dependencies.

$ npm install @vanilla-extract/babel-plugin

2/ Add the Babel plugin.

{ "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.

setupTests.ts
import '@vanilla-extract/css/disableRuntimeStyles';

Different formatting of identifiers (e.g. class names, keyframes, CSS Vars, etc) can be configured by selecting from the following options:

  • short identifiers are a 7+ character hash. e.g. hnw5tz3
  • 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.