Jest Vue Preprocessor

1.7.1 · abandoned · verified Tue Apr 21

jest-vue-preprocessor is a Jest transformer designed to enable the testing of Vue Single File Components (SFCs) within a Jest environment. Specifically, it allows Jest to correctly parse and process `.vue` files by transforming their templates and scripts into a format Jest can understand, supporting both ES6 (via Babel) and TypeScript. The current stable version is 1.7.1. This package was largely based on `vueify` and aimed to bridge the gap for Vue 2 projects wanting to use Jest for unit testing. Its primary differentiation is providing out-of-the-box support for `.vue` file compilation within Jest's isolated test environment, which Jest does not handle natively. However, it is an older package, last updated in 2019, and is primarily compatible with Vue 2.x and specific older versions of `vue-template-compiler`. Newer Vue projects (Vue 3 and above) typically use `vue-jest` for their testing needs due to significant breaking changes in Vue's compilation pipeline. Given its age and lack of recent updates, its release cadence is effectively ceased, and it should be considered abandoned for new projects.

Common errors

```
SyntaxError: Unexpected token '<'
```
cause Jest is attempting to parse a `.vue` file without it being transformed, usually because `jest-vue-preprocessor` is not correctly configured or not found.

fix Verify that `jest-vue-preprocessor` is listed correctly in your Jest `transform` configuration (e.g., `".*\\.(vue)$": "<rootDir>/node_modules/jest-vue-preprocessor"`) and that the package is installed.
```
Cannot find module 'vue-template-compiler'
```
cause The `vue-template-compiler` peer dependency is missing or installed at an incompatible version.

fix Install the correct version of the peer dependency: `npm install --save-dev vue-template-compiler@2.6.x` or `yarn add -D vue-template-compiler@2.6.x`.
```
Error: Cannot find module '@/'...
```
cause Jest's module resolver is unable to locate files imported using project aliases (like `@/`) because `moduleNameMapper` is not configured.

fix Add a `moduleNameMapper` configuration to your Jest settings that maps your project aliases to their corresponding file paths, e.g., `"^@/(.*)$": "<rootDir>/src/$1"`.

Warnings

breaking This package is not compatible with Vue 3. Vue 3 introduced significant breaking changes to its compilation pipeline and SFC format, rendering this Vue 2-era preprocessor unusable.
Fix: For Vue 3 projects, migrate your Jest setup to use `vue-jest` (version 5 or higher) or a similar modern transformer designed for Vue 3.
gotcha Strict peer dependency on `vue-template-compiler@2.6.x`. Using other versions of `vue-template-compiler` (e.g., 2.7.x or 3.x) will lead to build failures or unexpected behavior.
Fix: Ensure your project explicitly installs `vue-template-compiler@2.6.x` as a development dependency (`npm install --save-dev vue-template-compiler@2.6.x` or `yarn add -D vue-template-compiler@2.6.x`).
gotcha When using non-relative imports or aliases (e.g., `@/components/MyComponent.vue`), Jest's `moduleNameMapper` must be correctly configured to resolve these paths in your tests.
Fix: Add a `moduleNameMapper` entry to your Jest configuration, mapping your aliases to their physical paths (e.g., `"^@/(.*)$": "<rootDir>/src/$1"`).

Install

npm install jest-vue-preprocessor npm
yarn add jest-vue-preprocessor yarn
pnpm add jest-vue-preprocessor pnpm

Imports

transform configuration
wrong:
```
transform: { ".*\\.(vue)$": "jest-vue-preprocessor" }
```
correct:
```
transform: { ".*\\.(vue)$": "<rootDir>/node_modules/jest-vue-preprocessor" }
```
This configuration entry in your Jest settings (e.g., `jest.config.js` or `package.json` under `jest`) tells Jest to use `jest-vue-preprocessor` to transform `.vue` Single File Components. The `<rootDir>/node_modules/` prefix is often necessary for Jest to correctly locate the transformer.
moduleFileExtensions
wrong:
```
moduleFileExtensions: ["js"]
```
correct:
```
moduleFileExtensions: ["js", "vue"]
```
Adds the `.vue` extension to the list of files Jest will recognize when resolving modules, which is crucial for importing Vue components in tests.
moduleNameMapper
wrong:
```
moduleNameMapper: {}
```
correct:
```
moduleNameMapper: { "^@/(.*)$": "<rootDir>/src/$1" }
```
This is used to resolve non-relative or aliased imports (like `@/components/MyComponent.vue`) in your tests. This is a common requirement for Vue projects using build tools like Vue CLI. Ensure it matches your project's alias configurations.

Quickstart

This configuration snippet shows how to integrate `jest-vue-preprocessor` into your `package.json`'s Jest settings, enabling Jest to process `.vue` files and use Babel for JavaScript transformation.

{
  "jest": {
    "moduleFileExtensions": [
      "js",
      "vue"
    ],
    "mapCoverage": true,
    "transform": {
      "^.+\\.js$": "<rootDir>/node_modules/babel-jest",
      ".*\\.(vue)$": "<rootDir>/node_modules/jest-vue-preprocessor"
    }
  }
}

view raw JSON →