Vitest - Unknown file extension ".css"

Question

With React project set up with Vite and run tests with Vitest v2.1.1, we might see the following issue with CSS files:

TypeError: Unknown file extension .css for /path/to/css/file

How can we resolve it?

Answer 1

The error TypeError: Unknown file extension .css occurs because Vitest (running on Node.js) tries to import a CSS file as a standard ES Module, which Node doesn't support.

Handling CSS files automatically

As discussed in issue vitest-dev/vitest #3862, the solution to the problem is setting the deps.web.transformCss parameter to true.

@MinhTC gave a similar answer but did not provide an explanation. I would attach this alongside it.

The relevant part of the deps.web.transformCss section from the Vitest documentation reads as follows:

deps.web.transformCss

• Type: boolean
• Default: true

Should Vitest process CSS (.css, .scss, .sass, etc) files and resolve them like Vite does in the browser.

If CSS files are disabled with css options, this option will just silence ERR_UNKNOWN_FILE_EXTENSION errors.

---

WARNING
At the moment, this option only works with vmThreads and vmForks pools.

Although the setting is true by default, which would suggest that the error message mentioned in the question should not occur, the warning in the documentation clearly explains that the setting will only work with the pool: "vmThreads" or pool: "vmForks" configuration, what mentioned by @MinhTC.

export default defineConfig({
  test: {
    pool: "vmThreads", // or "vmForks"
  },
});

Fallback, handling CSS files manually if you cannot use transformCss

Although the file was missing from the question (which could possibly belong to a external package), and you only need to inform Vitest to use the external files with the server.deps.inline.

export default defineConfig({
  test: {
    // 1. Enable CSS processing
    css: true, 
    // OR if you need more control:
    // css: { include: /.+/ },

    server: {
      deps: {
        inline: [
          // 2. Add the name of the package that contains the CSS import
          "your-external-package-name",
          // You can also use regex to catch all CSS-heavy libs
          /package-prefix/
        ]
      }
    }
  }
});

While PR #3880 introduced deps.web.transformCss as a convenience feature to handle CSS automatically, it has a significant limitation: it currently only works with the experimentalVmThreads (or vmThreads / vmForks) pool. If you are using the default pool or your environment doesn't support the experimental Node.js loaders, transformCss will not be able to intercept the import before Node.js throws the ERR_UNKNOWN_FILE_EXTENSION error.

In these cases, the server.deps.inline approach is the only reliable way. By inlining the dependency, you explicitly tell Vitest to bypass the native Node.js loader and use Vite's internal transformation pipeline to convert the CSS into a JavaScript-compatible format.

Reference:

• vitest-dev/vitest issue #3862 - comment by sheremet-va
• vitest-dev/vitest PR #3880 - allow importing CSS and assets inside external dependencies

Answer 2

The solution is to set the pool option to use vmThreads or vmForks, like this:

export default defineConfig({
  test: {
    pool: "vmThreads",
  },
});

With this option, the following option deps.web.transformCss will be set to true by default, which will resolve the problem.