diff --git a/README.md b/README.md index c8676f5..8d32263 100644 --- a/README.md +++ b/README.md @@ -3,68 +3,149 @@

Babel Jest Boost

-

Brings tree-shaking to Jest, speeding up your test runs, using Babel

+

Brings tree-shaking* to Jest, speeding up your test runs, using babel-jest

## Overview -`babel-jest-boost` figures out the original export of your imported specifiers and rewrites your import statements to bypass barrel files and re-exports. This prevents jest from requiring, compiling and executing irrelevant code, speeding up your test runs. +`babel-jest-boost` makes your tests run faster by solving the [problem of unecessary imports from barrel files](https://github.com/jestjs/jest/issues/11234) -Assume the following structure: +It is a Babel plugin that re-writes your import statements to skip intermediate re-exports, thus bypassing barrel files. -```bash -. -├── lib -│   ├── lib.js # export function libFunc () {} -│   └── index.js # export * from './lib.js' -└── code.js # import { libFunc } from './lib'; -``` +## Usage -Only for the testing transpilation `babel-jest-boost` will convert the import statement in `code.js` to: +### 1. Install the package -```javascript -import { libFunc } from '/home/myuser/myproject/lib/lib.js'; +```bash +npm install -D @gtsopanoglou/babel-jest-boost ``` -It will also replace `jest.mock()` function calls in exaclty the same manner. +### 2. Update your babel-jest transformer -## Integration +#### Method 1 -### 1. Install the package +The simplest way to use this plugin is by replacing the `babel-jest` transformer with the `@gtsopanoglou/babel-jest-boost` in your jest config: -```bash -npm install -D @gtsopanoglou/babel-jest-boost +
+ jest.config.js + +```diff +"transform": { +- "\\.[jt]sx?$": "babel-jest" ++ "\\.[jt]sx?$": "@gtsopanoglou/babel-jest-boost" +} ``` +
+ -### 2. Update your babel-jest transformer -#### Option 1: `babel-jest-boost/plugin` +#### Method 2 -You may use `babel-jest-boost` as a regular babel plugin. It needs access to your jest config (`moduleNameMapper` and `modulePaths` in particular). To help you do that we export a `jestConfig` object: +If you are using a script file as your transformer, you can swap the `babel-jest` transformer factory for `gtsopanoglou/babel-jest-boost` in your script. Example from ejected CRA: +
+ jest.config.js + ```javascript -+ const { jestConfig } = require("@gtsopanoglou/babel-jest-boost/config"); - - ... - - plugins: [ - [ -+ require.resolve('@gtsopanoglou/babel-jest-boost/plugin'), -+ { jestConfig, /* babel-jest-boost options */ } - ] - ] +"transform": { + "^.+\\.(js|jsx|mjs|cjs|ts|tsx)$": "/config/jest/babelTransform.js", +}, +``` +
+ +
+ config/jest/babelTransform.js + +```diff +-const babelJest = require('babel-jest') ++const babelJest = require('@gtsopanoglou/babel-jest-boost') + +const hasJsxRuntime = (() => { + if (process.env.DISABLE_NEW_JSX_TRANSFORM === 'true') { + return false + } + + try { + require.resolve('react/jsx-runtime') + return true + } catch (e) { + return false + } +})() + +module.exports = babelJest.createTransformer({ + presets: [ + [ + require.resolve('babel-preset-react-app'), + { + runtime: hasJsxRuntime ? 'automatic' : 'classic' + } + ] + ], + babelrc: false, + configFile: false ++}, { ++ // babel-jest-boost plugin options +}) ``` +
-#### Option 2 (experimental): `babel-jest-boost/transformer` +#### Method 3 -This option **is not recommended yet** because it hasn't been tested thoroughly. Use can the pre-made transformer exported from `@gtsopanoglou/babel-jest-boost/transformer` which takes care of passing the `jestConfig` object for you: +You may use `babel-jest-boost` as a regular babel plugin. It needs access to your jest config (`moduleNameMapper` and `modulePaths` in particular). To help you do that we export a `jestConfig` object. Again an example from an ejected CRA: +
+ jest.config.js + ```javascript -- const babelJest = require("babel-jest").default; -+ const babelJestBoost = require("@gtsopanoglou/babel-jest-boost/transformer"); - -- module.exports = babelJest.createTransformer({ /* babel config */ }); -+ module.exports = babelJestBoost.createTransformer({ /* babel config */ }, { /* babel-jest-boost options */ }); +"transform": { + "^.+\\.(js|jsx|mjs|cjs|ts|tsx)$": "/config/jest/babelTransform.js", +}, +``` +
+ +
+ config/jest/babelTransform.js + +```diff +const babelJest = require('babel-jest') ++const { jestConfig } = require('@gtsopanoglou/babel-jest-boost/config') + +const hasJsxRuntime = (() => { + if (process.env.DISABLE_NEW_JSX_TRANSFORM === 'true') { + return false + } + + try { + require.resolve('react/jsx-runtime') + return true + } catch (e) { + return false + } +})() + +module.exports = babelJest.createTransformer({ + presets: [ + [ + require.resolve('babel-preset-react-app'), + { + runtime: hasJsxRuntime ? 'automatic' : 'classic' + } + ] + ], ++ plugins: [ ++ [ ++ require.resolve('@gtsopanoglou/babel-jest-boost/plugin'), ++ { ++ jestConfig, ++ // babel-jest-boost plugin options ++ } ++ ] ++ ], + babelrc: false, + configFile: false +}) ``` +
### 3. Run your tests, prevent breakages