docs: Document jest's transformIgnorePatterns option to avoid pitfall (#3523) [ci skip]

Author: LinusBorg

docs/config/README.md

@@ -188,6 +188,14 @@ Deprecated since Vue CLI 3.3, please use [`publicPath`](#publicPath) instead.
 
   By default `babel-loader` ignores all files inside `node_modules`. If you want to explicitly transpile a dependency with Babel, you can list it in this option.
 
+::: warning Jest config
+This option is not respected by the [cli-unit-jest plugin](#jest), because in jest, we don't have to transpile code from `/node_modules` unless it uses non-standard features - Node >8.11 supports the latest ECMAScript features already.
+
+However, jest sometimes has to transform content from node_modules if that code uses ES6 `import`/`export` syntax. In that case, use the `tranformIgnorePatterns` option in `jest.config.js`.
+
+See [the plugin's README](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-plugin-unit-jest/README.md) for more information.
+:::
+
 ### productionSourceMap
 
 - Type: `boolean`

packages/@vue/cli-plugin-unit-jest/README.md

@@ -21,7 +21,7 @@ Note that directly running `jest` will fail because the Babel preset requires hi
 
 If you want to debug your tests via the Node inspector, you can run the following:
 
-``` sh
+```sh
 # macOS or linux
 node --inspect-brk ./node_modules/.bin/vue-cli-service test:unit
 
@@ -35,6 +35,36 @@ Jest can be configured via `jest.config.js` in your project root, or the `jest`
 
 ## Installing in an Already Created Project
 
-``` sh
+```sh
 vue add @vue/unit-jest
 ```
+
+## Transform dependencies from `/node_modules`
+
+By default, jest doesn't transform anything from `/nodee_modules`.
+
+Since jest runs in node, we also don't have to transpile anything that uses modern ECMAScript features as Node >=8 already supports these features, so it's a sensible default. cli-plugin-jest also doesn't respect the `transpileDependencies` option in `vue.config.js` for the same reason.
+
+However, we have (at least) three cases where we do need to transpile code from `/node_modules` in jest:
+
+1. Usage of ES6 `import`/`export` statements, which have to be compiled to commonjs `module.exports`
+2. Single File Components (`.vue` files) which have to be run through `vue-jest`
+3. Typescript code
+
+To do this, we need to add an exception to the `tranformIgnorePatterns` option of jest. This is its default value:
+
+```javascript
+transformIgnorePatterns: ['/node_modules/']
+```
+
+We have to add exceptions to this pattern with a RegExp negative lookahead:
+
+```javascript
+transformIgnorePatterns: ['/node_modules/(?!name-of-lib-o-transform)']
+```
+
+To exclude multiple libraries:
+
+```javascript
+transformIgnorePatterns: ['/node_modules/(?!lib-to-transform|other-lib)']
+```

packages/@vue/cli-plugin-unit-jest/generator/index.js

@@ -23,6 +23,7 @@ module.exports = (api, _, __, invoking) => {
         '^.+\\.vue$': 'vue-jest',
         '.+\\.(css|styl|less|sass|scss|svg|png|jpg|ttf|woff|woff2)$': 'jest-transform-stub'
       },
+      'transformIgnorePatterns': ['/node_modules/'],
       // support the same @ -> src alias mapping in source code
       'moduleNameMapper': {
         '^@/(.*)$': '<rootDir>/src/$1'