vite: Don't pass through plugins by default, add unstable_pluginFilter option (#1537)

Author: askoufis

.changeset/metal-jars-fail.md

@@ -0,0 +1,7 @@
+---
+'@vanilla-extract/vite-plugin': major
+---
+
+Change the plugin name from `"vanilla-extract"` to the more [conventional][plugin conventions] `"vite-plugin-vanilla-extract"`
+
+[plugin conventions]: https://vite.dev/guide/api-plugin.html#conventions

.changeset/three-shirts-knock.md

@@ -0,0 +1,37 @@
+---
+'@vanilla-extract/vite-plugin': major
+---
+
+BREAKING CHANGE: User-configured vite plugins are no longer forwarded through to the Vanilla Extract compiler by default. This should not affect most consumers.
+
+Previously, all vite plugins except for a select few incompatible plugins were forwarded through. This resulted in a constant game of whack-a-mole as new plugins were added to the list of incompatible plugins as issues were discovered.
+
+Framework-specific plugins, as well as plugins that handle assets and build output, tend not to be relevant to Vanilla Extract code, and in some cases cause more harm than good.
+
+For that reason, in this release only the `vite-tsconfig-paths` plugin is fowarded through by default. This is a relatively common plugin that is know to be compatible with the Vanilla Extract compiler. 
+
+In most cases users should not need to forward any additional plugins through to the Vanilla Extract compiler. However, if such a case arises, a plugin filter function can be provided via the `unstable_pluginFilter` option:
+
+```ts
+// vite.config.ts
+
+import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
+import { vitePluginFoo } from 'vite-plugin-foo';
+
+export default defineConfig({
+  plugins: [
+    vitePluginFoo(),
+    vanillaExtractPlugin({
+      // Only forward the `vite-plugin-foo` plugin through to the Vanilla Extract compiler
+      unstable_pluginFilter: ({ name, mode }) => plugin.name === 'vite-plugin-foo',
+    }),
+  ],
+});
+```
+
+> [!NOTE]
+> When providing a plugin filter function, the `vite-tsconfig-paths` plugin will no longer be forwarded through by default.
+> If you wish to forward this plugin through, you must include it in your filter function.
+
+> [!IMPORTANT]
+> The `unstable_pluginFilter` API is considered unstable and may be changed or removed without notice in a future non-major version.

packages/vite-plugin/src/index.ts

@@ -18,37 +18,48 @@ import {
   normalizePath,
 } from '@vanilla-extract/integration';
 
+const PLUGIN_NAME = 'vite-plugin-vanilla-extract';
 const virtualExtCss = '.vanilla.css';
 
 const isVirtualId = (id: string) => id.endsWith(virtualExtCss);
 const fileIdToVirtualId = (id: string) => `${id}${virtualExtCss}`;
 const virtualIdToFileId = (virtualId: string) =>
   virtualId.slice(0, -virtualExtCss.length);
 
-const removeIncompatiblePlugins = (plugin: PluginOption) =>
-  typeof plugin === 'object' &&
-  plugin !== null &&
-  'name' in plugin &&
-  // Prevent an infinite loop where the compiler creates a new instance of the plugin,
-  // which creates a new compiler, which creates a new instance of the plugin, etc.
-  plugin.name !== 'vanilla-extract' &&
-  // Skip Remix because it throws an error if it's not loaded with a config file.
-  // If it _is_ loaded with a config file, it will create an infinite loop because it
-  // also has a child compiler which uses the same mechanism to load the config file.
-  // https://github.com/remix-run/remix/pull/7990#issuecomment-1809356626
-  // Additionally, some internal Remix plugins rely on a `ctx` object to be initialized by
-  // the main Remix plugin, and may not function correctly without it. To address this, we
-  // filter out all Remix-related plugins.
-  !plugin.name.startsWith('remix') &&
-  // As React-Router plugin works the same as Remix plugin, also ignore it.
-  !plugin.name.startsWith('react-router');
+const isPluginObject = (plugin: PluginOption): plugin is Plugin =>
+  typeof plugin === 'object' && plugin !== null && 'name' in plugin;
+
+type PluginFilter = (filterProps: {
+  /** The name of the plugin */
+  name: string;
+  /**
+   * The `mode` vite is running in.
+   * @see https://vite.dev/guide/env-and-mode.html#modes
+   */
+  mode: string;
+}) => boolean;
 
 interface Options {
   identifiers?: IdentifierOption;
+  unstable_pluginFilter?: PluginFilter;
   unstable_mode?: 'transform' | 'emitCss';
 }
+
+// Plugins that we know are compatible with the `vite-node` compiler
+// and don't need to be filtered out.
+const COMPATIBLE_PLUGINS = ['vite-tsconfig-paths'];
+
+const defaultPluginFilter: PluginFilter = ({ name }) =>
+  COMPATIBLE_PLUGINS.includes(name);
+
+const withUserPluginFilter =
+  ({ mode, pluginFilter }: { mode: string; pluginFilter: PluginFilter }) =>
+  (plugin: Plugin) =>
+    pluginFilter({ name: plugin.name, mode });
+
 export function vanillaExtractPlugin({
   identifiers,
+  unstable_pluginFilter: pluginFilter = defaultPluginFilter,
   unstable_mode: mode = 'emitCss',
 }: Options = {}): Plugin {
   let config: ResolvedConfig;
@@ -98,7 +109,7 @@ export function vanillaExtractPlugin({
   }
 
   return {
-    name: 'vanilla-extract',
+    name: PLUGIN_NAME,
     configureServer(_server) {
       server = _server;
     },
@@ -147,7 +158,8 @@ export function vanillaExtractPlugin({
           ...configForViteCompiler,
           plugins: configForViteCompiler?.plugins
             ?.flat()
-            .filter(removeIncompatiblePlugins),
+            .filter(isPluginObject)
+            .filter(withUserPluginFilter({ mode: config.mode, pluginFilter })),
         };
 
         compiler = createCompiler({