externals option in VanillaExtractPlugin is silently ignored — array is nested instead of spread into ExternalsPlugin

[vivekgupta5]

When passing an externals array to createVanillaExtractPlugin (or VanillaExtractPlugin directly), the externals are silently ignored because the array is nested as a single element rather than spread into the ExternalsPlugin call inside the child compiler.

To Reproduce

Configure the plugin with externals:

const { createVanillaExtractPlugin } = require("@vanilla-extract/next-plugin");

const withVanillaExtract = createVanillaExtractPlugin({
  externals: ['react', 'react-dom', 'my-package'],
});

Despite the configuration, the child compiler still attempts to bundle react, react-dom, and my-package — the externals have no effect.

Expected behavior

Packages listed in externals should be excluded from the child compiler's webpack bundle, resolved instead via Node.js require() at CSS extraction time.

Actual behavior

The externals are silently ignored. The child compiler still tries to bundle the listed packages, causing crashes when those packages contain code that can't run in the child compiler's isolated environment (e.g. React components that reference $RefreshReg$ injected by React Fast Refresh).

Root Cause

In plugin-13fbd189.cjs.dev.js:126 (and equivalent prod/esm variants), the externals array is passed as a nested element rather than being spread into the outer array:

// Current (buggy) — externals array is nested as one element
new ExternalsPlugin('commonjs', [
  '@vanilla-extract/css',
  '@vanilla-extract/css/fileScope',
  externals  // ← should be ...externals
]).apply(childCompiler);

ExternalsPlugin receives ['@vanilla-extract/css', '@vanilla-extract/css/fileScope', ['react', 'react-dom', 'my-package']] — the nested array is not a valid external entry and is effectively ignored.

Proposed Fix

Spread the externals array:

new ExternalsPlugin('commonjs', [
  '@vanilla-extract/css',
  '@vanilla-extract/css/fileScope',
  ...(Array.isArray(externals) ? externals : [externals].filter(Boolean))
]).apply(childCompiler);

The same fix needs to be applied to all three dist variants:

• plugin-13fbd189.cjs.dev.js (line 126)
• plugin-3616fe54.cjs.prod.js (line 126)
• plugin-12db1f52.esm.js (line 124)

---

Additional Finding: externals is undocumented and typed as any

Inspecting the published type definitions reveals:

interface PluginOptions {
  test?: RuleSetRule['test'];
  identifiers?: IdentifierOption;
  outputCss?: boolean;
  externals?: any;  // ← no type constraint
  /** @deprecated */
  allowRuntime?: boolean;
}

The externals option is not documented anywhere — not in the README, not on the vanilla-extract documentation site. The type externals?: any:

• Provides no guidance on whether it accepts a string, string[], or webpack's Externals type
• Gives users no way to discover the correct usage
• Allowed this bug to go undetected since there's no contract to validate against

Suggested improvements alongside the fix:

1. Fix the array spreading bug at line 126 across all dist variants
2. Type externals properly — e.g. externals?: string | string[] or webpack's ExternalItem | ExternalItem[]
3. Add documentation explaining what externals does and when to use it

---

Environment

Package	Version
@vanilla-extract/webpack-plugin	2.3.25
@vanilla-extract/next-plugin	2.4.17
next	16.1.0
node	22.22.0

Workaround

Until this is fixed, avoid importing from packages that include React code in .css.ts files. Import directly from a CSS-only sub-package instead:

// Instead of the barrel export (crashes child compiler)
import { tokens } from "my-package";

// Import from the theme/tokens-only sub-package
import { tokens } from "my-package-theme";

[askoufis]

Thanks for raising this. This has been addressed in the latest versions of the next and webpack plugins.

[vivekgupta5]

Thank you @askoufis for a quick turnaround.

Do you guys have a plan to rollout a new version for @vanilla-extract/next-plugin?

[askoufis]

Yes, it was released shortly after the bug fix was merged. https://github.com/vanilla-extract-css/vanilla-extract/releases/tag/%40vanilla-extract%2Fnext-plugin%402.5.2

[vivekgupta5]

Sorry, I completely missed that.

[vivekgupta5]

Hi @askoufis,
Thanks for the fix in 2.5.2. After testing, we're still seeing $RefreshReg$ is not defined in our setup. Wanted to share our findings along with a minimal reproduction.

Environment:

• @vanilla-extract/[email protected]
• Next.js 16 (with React Refresh enabled by default)

What the externals fix resolved:
The nested array bug is fixed — packages listed in externals are now correctly excluded from the child compiler's bundling.

What's still failing:
Even with the correct externals config, Next.js 16's React Refresh babel transform matches .ts files broadly and appears to be inherited by the child compiler via createChildCompiler(). This injects $RefreshReg$ calls into .css.ts files, but the child compiler has no React Refresh runtime, causing the crash.

Minimal reproduction:
next.config.js:

const { createVanillaExtractPlugin } = require("@vanilla-extract/next-plugin");

const withVanillaExtract = createVanillaExtractPlugin({
  externals: ['react', 'react-dom', 'my-component-library'],
});

module.exports = withVanillaExtract({});

styles.css.ts:

// Importing from a barrel that re-exports both React components AND design tokens
import { tokens } from "my-component-library";

export const myStyle = style({ color: tokens.color.primary });

Where my-component-library is a barrel package that re-exports:

• React components (from a sub-package)
• Design tokens (from a separate theme sub-package e.g. my-component-library-theme)

Key observation:
Changing the import to the theme sub-package directly resolves the error:

// Works
import { tokens } from "my-component-library-theme";

// Crashes with $RefreshReg$ is not defined
import { tokens } from "my-component-library";

This suggests the React Refresh transform is being applied to .css.ts files by the child compiler even when the barrel is listed in externals. The externals fix prevents bundling, but the transform still runs and injects $RefreshReg$.

Suggested fix direction:
The child compiler may need to explicitly strip React Refresh loaders from its inherited module rules during setup.

Happy to provide additional details if helpful. Thanks for your continuous support!

[askoufis]

There are existing issues in the repo about fixing the $RefreshReg$ problem. We've yet to come up with a fix that works in all cases so one of those workarounds might be necessary in your case.