1 | # Cypress Webpack Preprocessor [![CircleCI](https://circleci.com/gh/cypress-io/cypress-webpack-preprocessor.svg?style=svg)](https://circleci.com/gh/cypress-io/cypress-webpack-preprocessor) [![semantic-release][semantic-image] ][semantic-url]
|
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 | This plugin (and all Cypress plugins) run in Cypress's own version of Node. If you require npm packages or your own code into the pluginsFile, they needs to be compatible with [the version of Node that Cypress uses]((https://github.com/cypress-io/cypress/blob/develop/.node-version)).
|
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 webpack = require('@cypress/webpack-preprocessor')
|
39 |
|
40 | module.exports = (on) => {
|
41 | on('file:preprocessor', webpack())
|
42 | }
|
43 | ```
|
44 |
|
45 | ## Options
|
46 |
|
47 | Pass in options as the second argument to `webpack`:
|
48 |
|
49 | ```javascript
|
50 | const webpack = require('@cypress/webpack-preprocessor')
|
51 |
|
52 | module.exports = (on) => {
|
53 | const options = {
|
54 | // send in the options from your webpack.config.js, so it works the same
|
55 | // as your app's code
|
56 | webpackOptions: require('../../webpack.config'),
|
57 | watchOptions: {},
|
58 | }
|
59 |
|
60 | on('file:preprocessor', webpack(options))
|
61 | }
|
62 | ```
|
63 |
|
64 | ### webpackOptions
|
65 |
|
66 | Object of webpack options. Just `require` in the options from your `webpack.config.js` to use the same options as your app.
|
67 |
|
68 | **Default**:
|
69 |
|
70 | ```javascript
|
71 | {
|
72 | module: {
|
73 | rules: [
|
74 | {
|
75 | test: /\.jsx?$/,
|
76 | exclude: [/node_modules/],
|
77 | use: [{
|
78 | loader: 'babel-loader',
|
79 | options: {
|
80 | presets: ['@babel/preset-env'],
|
81 | },
|
82 | }],
|
83 | },
|
84 | ],
|
85 | },
|
86 | }
|
87 | ```
|
88 |
|
89 | Source maps are always enabled unless explicitly disabled by specifying `devtool: false`.
|
90 |
|
91 | ### watchOptions
|
92 |
|
93 | Object of options for watching. See [webpack's docs](https://webpack.js.org/configuration/watch).
|
94 |
|
95 | **Default**: `{}`
|
96 |
|
97 | ### additionalEntries
|
98 |
|
99 | An array of file path strings for additional entries to be included in the bundle.
|
100 |
|
101 | 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.
|
102 |
|
103 | **Default**: `[]`
|
104 |
|
105 | **Example**:
|
106 |
|
107 | ```javascript
|
108 | const webpack = require('@cypress/webpack-preprocessor')
|
109 |
|
110 | module.exports = (on) => {
|
111 | const options = {
|
112 | webpackOptions: require('../../webpack.config'),
|
113 | additionalEntries: ['./app/some-module.js'],
|
114 | }
|
115 |
|
116 | on('file:preprocessor', webpack(options))
|
117 | }
|
118 | ```
|
119 |
|
120 | ## Modifying default options
|
121 |
|
122 | The default options are provided as `webpack.defaultOptions` so they can be more easily modified.
|
123 |
|
124 | 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:
|
125 |
|
126 | ```javascript
|
127 | const webpack = require('@cypress/webpack-preprocessor')
|
128 |
|
129 | module.exports = (on) => {
|
130 | const options = webpack.defaultOptions
|
131 | options.webpackOptions.module.rules[0].use[0].options.presets.push('babel-preset-stage-3')
|
132 |
|
133 | on('file:preprocessor', webpack(options))
|
134 | }
|
135 | ```
|
136 |
|
137 | ## Contributing
|
138 |
|
139 | Use the [version of Node that matches Cypress](https://github.com/cypress-io/cypress/blob/develop/.node-version).
|
140 |
|
141 | Run all tests once:
|
142 |
|
143 | ```shell
|
144 | npm test
|
145 | ```
|
146 |
|
147 | Run tests in watch mode:
|
148 |
|
149 | ```shell
|
150 | npm run test-watch
|
151 | ```
|
152 |
|
153 | ## License
|
154 |
|
155 | This project is licensed under the terms of the [MIT license](/LICENSE.md).
|
156 |
|
157 | [semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
158 | [semantic-url]: https://github.com/semantic-release/semantic-release
|