1 | # Cypress Webpack Preprocessor
|
2 |
|
3 | Cypress preprocessor for bundling JavaScript via webpack
|
4 |
|
5 | ## Installation
|
6 |
|
7 | ```sh
|
8 | npm install --save-dev @cypress/webpack-preprocessor
|
9 | ```
|
10 |
|
11 | This package relies on the following [peer dependencies](https://docs.npmjs.com/files/package.json#peerdependencies):
|
12 |
|
13 | * @babel/core
|
14 | * @babel/preset-env
|
15 | * babel-loader
|
16 | * webpack
|
17 |
|
18 | It is likely you already have these installed either directly or as a transient dependency, but if not, you will need to install them.
|
19 |
|
20 | ```sh
|
21 | npm install --save-dev @babel/core @babel/preset-env babel-loader webpack
|
22 | ```
|
23 |
|
24 | ## Compatibility
|
25 |
|
26 | This version is only compatible with webpack 4.x+ and Babel 7.x+.
|
27 |
|
28 | * If you need webpack 2 or 3 support, use `@cypress/webpack-preprocessor` 1.x
|
29 | * If you need Babel 6 support, use `@cypress/webpack-preprocessor` <= 2.x
|
30 |
|
31 | By default, this plugin (and all Cypress plugins) run in the Node version that is bundled with Cypress. Alternatively, you can use the Node found on your system by setting [nodeVersion: system](https://on.cypress.io/configuration#Node-version) configuration option. A common use case for using the system Node are native dependencies like `node-sass`.
|
32 |
|
33 | ## Usage
|
34 |
|
35 | In your project's [plugins file](https://on.cypress.io/guides/tooling/plugins-guide.html):
|
36 |
|
37 | ```javascript
|
38 | const webpackPreprocessor = require('@cypress/webpack-preprocessor')
|
39 |
|
40 | module.exports = (on) => {
|
41 | on('file:preprocessor', webpackPreprocessor())
|
42 | }
|
43 | ```
|
44 |
|
45 | ## Examples
|
46 |
|
47 | - [React app](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor/examples/react-app) shows how to point Cypress at Webpack configuration from `react-scripts` dependency
|
48 | - [use-babelrc](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor/examples/use-babelrc) shows how to use your project's `.babelrc` with Webpack
|
49 | - [use-ts-loader](https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor/examples/use-ts-loader) shows how to transpile TypeScript specs following [Webpack TypeScript guide](https://webpack.js.org/guides/typescript/)
|
50 |
|
51 | ## Options
|
52 |
|
53 | Pass in options as the second argument to `webpack`:
|
54 |
|
55 | ```javascript
|
56 | const webpackPreprocessor = require('@cypress/webpack-preprocessor')
|
57 |
|
58 | module.exports = (on) => {
|
59 | const options = {
|
60 | // send in the options from your webpack.config.js, so it works the same
|
61 | // as your app's code
|
62 | webpackOptions: require('../../webpack.config'),
|
63 | watchOptions: {},
|
64 | }
|
65 |
|
66 | on('file:preprocessor', webpackPreprocessor(options))
|
67 | }
|
68 | ```
|
69 |
|
70 | ### webpackOptions
|
71 |
|
72 | Object of webpack options. Just `require` in the options from your `webpack.config.js` to use the same options as your app.
|
73 |
|
74 | **Default**:
|
75 |
|
76 | ```javascript
|
77 | {
|
78 | mode: 'development',
|
79 | module: {
|
80 | rules: [
|
81 | {
|
82 | test: /\.jsx?$/,
|
83 | exclude: [/node_modules/],
|
84 | use: [{
|
85 | loader: 'babel-loader',
|
86 | options: {
|
87 | presets: ['@babel/preset-env'],
|
88 | },
|
89 | }],
|
90 | },
|
91 | ],
|
92 | },
|
93 | }
|
94 | ```
|
95 |
|
96 | Source maps are **always enabled** unless explicitly disabled by specifying `devtool: false`.
|
97 |
|
98 | Webpack [mode](https://webpack.js.org/configuration/mode/) is set to `development` if not present. You can set `mode` to "development", "production" or "none".
|
99 |
|
100 | ### use babelrc
|
101 |
|
102 | If you have a `.babelrc` file and would like to use it, then you must delete `options.presets` from the default Webpack options
|
103 |
|
104 | ```js
|
105 | const webpackPreprocessor = require('@cypress/webpack-preprocessor')
|
106 | const defaults = webpackPreprocessor.defaultOptions
|
107 | module.exports = (on) => {
|
108 | delete defaults.webpackOptions.module.rules[0].use[0].options.presets
|
109 | on('file:preprocessor', webpackPreprocessor(defaults))
|
110 | }
|
111 | ```
|
112 |
|
113 | ### watchOptions
|
114 |
|
115 | Object of options for watching. See [webpack's docs](https://webpack.js.org/configuration/watch).
|
116 |
|
117 | **Default**: `{}`
|
118 |
|
119 | ### additionalEntries
|
120 |
|
121 | An array of file path strings for additional entries to be included in the bundle.
|
122 |
|
123 | By necessity, this preprocessor sets the entry point for webpack as the spec file or support file. The `additionalEntries` option allows you to specify more entry points in order to utilize webpack's [multi-main entry](https://webpack.js.org/concepts/entry-points/#single-entry-shorthand-syntax). This allows runtime dependency resolution.
|
124 |
|
125 | **Default**: `[]`
|
126 |
|
127 | **Example**:
|
128 |
|
129 | ```javascript
|
130 | const webpackPreprocessor = require('@cypress/webpack-preprocessor')
|
131 |
|
132 | module.exports = (on) => {
|
133 | const options = {
|
134 | webpackOptions: require('../../webpack.config'),
|
135 | additionalEntries: ['./app/some-module.js'],
|
136 | }
|
137 |
|
138 | on('file:preprocessor', webpackPreprocessor(options))
|
139 | }
|
140 | ```
|
141 |
|
142 | ## Modifying default options
|
143 |
|
144 | The default options are provided as `webpack.defaultOptions` so they can be more easily modified.
|
145 |
|
146 | If, for example, you want to update the options for the `babel-loader` to add the [stage-3 preset](https://babeljs.io/docs/plugins/preset-stage-3/), you could do the following:
|
147 |
|
148 | ```javascript
|
149 | const webpackPreprocessor = require('@cypress/webpack-preprocessor')
|
150 |
|
151 | module.exports = (on) => {
|
152 | const options = webpackPreprocessor.defaultOptions
|
153 | options.webpackOptions.module.rules[0].use[0].options.presets.push('babel-preset-stage-3')
|
154 |
|
155 | on('file:preprocessor', webpackPreprocessor(options))
|
156 | }
|
157 | ```
|
158 |
|
159 | ## Debugging
|
160 |
|
161 | You can see debug messages from this module by running with environment variable
|
162 |
|
163 | ```
|
164 | DEBUG=cypress:webpack
|
165 | ```
|
166 |
|
167 | You can see Webpack bundle diagnostic output (timings, chunks, sizes) by running with environment variable
|
168 |
|
169 | ```
|
170 | DEBUG=cypress:webpack:stats
|
171 | ```
|
172 | ![Webpack stats](images/webpack-stats.png)
|
173 |
|
174 | ## Contributing
|
175 |
|
176 | Use the [version of Node that matches Cypress](https://github.com/cypress-io/cypress/blob/develop/.node-version).
|
177 |
|
178 | Build the typescript files:
|
179 |
|
180 | ```shell
|
181 | yarn build
|
182 | ```
|
183 |
|
184 | Watch the typescript files and rebuild on file change:
|
185 |
|
186 | ```shell
|
187 | yarn build --watch
|
188 | ```
|
189 |
|
190 | Run all tests once:
|
191 |
|
192 | ```shell
|
193 | npm test
|
194 | ```
|
195 |
|
196 | Run tests in watch mode:
|
197 |
|
198 | ```shell
|
199 | npm run test-watch
|
200 | ```
|
201 |
|
202 | ## License
|
203 |
|
204 | This project is licensed under the terms of the [MIT license](/LICENSE.md).
|
205 |
|
206 | [semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
207 | [semantic-url]: https://github.com/semantic-release/semantic-release
|
208 |
|
209 | ## Changelog
|
210 |
|
211 | [Changelog](./CHANGELOG.md)
|