Fix broken webpack/next.js externals, add docs (#1722)

Author: askoufis

.changeset/sunny-years-knock.md

@@ -0,0 +1,6 @@
+---
+'@vanilla-extract/webpack-plugin': patch
+'@vanilla-extract/next-plugin': patch
+---
+
+Fixes a bug where the `externals` option was silently ignored

packages/webpack-plugin/src/compiler.ts

@@ -1,7 +1,11 @@
 import type { LoaderContext } from './types';
 import createCompat from './compat';
 
-// Should be "ExternalsItem" but webpack doesn't expose it
+// Webpack exposes the `Externals` type which is a union of several types.
+// We likely intended to only accept a subset of these, but chose to use `any`.
+// We handle potential array inputs, but really we should be more specific about what we accept
+// here, or handling all types. Changing this type would be a breaking change,
+// so we can look at this in a future major release.
 type Externals = any;
 
 interface CompilationResult {
@@ -131,7 +135,7 @@ function compileVanillaSource(
     new ExternalsPlugin('commonjs', [
       '@vanilla-extract/css',
       '@vanilla-extract/css/fileScope',
-      externals,
+      ...(Array.isArray(externals) ? externals : [externals]),
     ]).apply(childCompiler);
 
     let source: string;

packages/webpack-plugin/src/plugin.ts

@@ -57,6 +57,10 @@ export interface PluginOptions {
   test?: RuleSetRule['test'];
   identifiers?: IdentifierOption;
   outputCss?: boolean;
+  /**
+   * Effectively `ExternalItem[]` from webpack. Currently typed as `any` as this type was
+   * previously not exposed. The `any` type will be fixed in the next major version.
+   */
   externals?: any;
   /** @deprecated */
   allowRuntime?: boolean;

site/docs/integrations/next.md

@@ -76,6 +76,14 @@ const withVanillaExtract = createVanillaExtractPlugin({
 
 Each integration will set a default value based on the configuration options passed to the bundler.
 
+### externals
+
+Effectively [`ExternalItem[]`] from webpack.
+Currently typed as `any` as this type was previously not exposed.
+The `any` type will be fixed in the next major version.
+
+[`ExternalItem[]`]: https://github.com/webpack/webpack/blob/9211be0f7a04feb45e1074e6cf848a657dd82ebc/declarations/WebpackOptions.d.ts#L207-L211
+
 ### 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.

site/docs/integrations/webpack.md

@@ -102,3 +102,11 @@ new VanillaExtractPlugin({
 ```
 
 Each integration will set a default value based on the configuration options passed to the bundler.
+
+### externals
+
+Effectively [`ExternalItem[]`] from webpack.
+Currently typed as `any` as this type was previously not exposed.
+The `any` type will be fixed in the next major version.
+
+[`ExternalItem[]`]: https://github.com/webpack/webpack/blob/9211be0f7a04feb45e1074e6cf848a657dd82ebc/declarations/WebpackOptions.d.ts#L207-L211