Next.js

A plugin for integrating vanilla-extract with Next.js.

Installation

npm install --save-dev @vanilla-extract/next-plugin

Setup

If you don’t have a next.config.js or next.config.ts file in the root of your project, create one. Then add the plugin to your Next.js config file:

next.config.ts
import type { NextConfig } from 'next';
import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';
const withVanillaExtract = createVanillaExtractPlugin();

const nextConfig: NextConfig = {};

export default withVanillaExtract(nextConfig);

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

next.config.ts
import type { NextConfig } from 'next';
import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';
import createMDX from '@next/mdx';

const withVanillaExtract = createVanillaExtractPlugin();

const withMDX = createMDX({
  extension: /\.mdx$/
});

const nextConfig: NextConfig = {};

export default withVanillaExtract(withMDX(nextConfig));

Version Support

Next.js >= 16.x: Both Turbopack and Webpack are supported
Next.js <= 15.x: Only Webpack is supported

Configuration

The plugin accepts the following as optional configuration, passed to createVanillaExtractPlugin.

identifiers

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
A custom identifier function takes an object parameter with properties hash, filePath, debugId, and packageName, and returns a customized identifier. e.g.

next.config.ts
import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';

const withVanillaExtract = createVanillaExtractPlugin({
  identifiers: ({ hash }) => `prefix_${hash}`
});

Each integration will set a default value based on the configuration options passed to the bundler.

unstable_turbopack

⚠️ Turbopack support is experimental. Its API is unstable and may undergo breaking changes in non-major versions. Additionally, it may not handle all features supported by Next.js.

You can control Turbopack autoconfiguration using unstable_turbopack.mode:

off: (default) never configure Turbopack (i.e. use Webpack)
auto: enable Turbopack config only when Next >= 16.0.0
on: force-enable Turbopack config

For example:

next.config.ts
import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';

const withVanillaExtract = createVanillaExtractPlugin({
  unstable_turbopack: { mode: 'auto' }
});

export default withVanillaExtract({});

If you already manage turbopack.rules yourself for the same file globs, the plugin may throw to avoid rule conflicts. In that case, set mode: 'off' and apply your Turbopack config manually.

By default Turbopack integration processes **/*.css.{js,cjs,mjs,jsx,ts,tsx} files. You can override this with unstable_turbopack.glob:

next.config.ts
import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';

const withVanillaExtract = createVanillaExtractPlugin({
  unstable_turbopack: {
    mode: 'auto',
    glob: ['**/*.css.ts', '**/*.css.tsx']
  }
});

export default withVanillaExtract({});

Transpiling Vanilla Extract-dependent Libraries

By default, Next.js does not allow importing of TypeScript files outside of the app root.

If your application depends on a TypeScript library, whether that be a local package within your app’s monorepo, or a dependency inside node_modules, and that library styles its components with Vanilla Extract, but does not compile its styles, then that library needs to be added to transpilePackages in your Next.js config:

App.tsx
import { Button } from '@company/design-system';

export default function App() {
  // This is unstyled and/or throws errors about Vanilla Extract being used in runtime
  return <Button>Hello, World!</Button>;
}

next.config.ts
import type { NextConfig } from 'next';
import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';
const withVanillaExtract = createVanillaExtractPlugin();

const nextConfig: NextConfig = {
  transpilePackages: ['@company/design-system']
};

// Next.js Vanilla Extract integration will now compile @company/design-system styles
export default withVanillaExtract(nextConfig);

PreviousGatsby

NextParcel