UNPKG

9.28 kBMarkdownView Raw
1# Documentation
2
3## Basic Setup
4
5Below is an example of how to add the plugin to a webpack config:
6
7```javascript
8const LicenseWebpackPlugin = require('license-webpack-plugin').LicenseWebpackPlugin;
9
10module.exports = {
11 plugins: [
12 new LicenseWebpackPlugin()
13 ]
14};
15```
16
17## Configuration
18
19* **`stats`** - toggle warnings and errors on/off (default: report warnings and errors)
20
21Example:
22```javascript
23new LicenseWebpackPlugin({
24 stats: {
25 warnings: true,
26 errors: true
27 }
28});
29```
30
31* **`licenseInclusionTest`** - filter which licenses get included in the report (default: capture all licenses)
32
33Example:
34```javascript
35new LicenseWebpackPlugin({
36 licenseInclusionTest: (licenseType) => (licenseType === 'MIT')
37});
38```
39
40Notes: All license identifiers in npm packages are supposed to follow SPDX format. If your requirements are very specific, it is recommended to set up this option using the [`spdx-satisfies`](https://www.npmjs.com/package/spdx-satisfies) package. The plugin does not provide the `spdx-satisfies` package, so you must install it separately if you want to use it.
41
42Example using `spdx-satisfies`:
43
44```javascript
45const satisfies = require('spdx-satisfies');
46
47new LicenseWebpackPlugin({
48 licenseInclusionTest: (licenseType) => satisfies(licenseType, '(ISC OR MIT)')
49});
50```
51
52* **`outputFilename`** - customize the license report filename (default: `'[name].licenses.txt'`)
53
54Example:
55```javascript
56new LicenseWebpackPlugin({
57 outputFilename: '[name].[hash].licenses.txt'
58});
59```
60
61* **`unacceptableLicenseTest`** - error out on unacceptable license (default: disabled)
62
63Example:
64```javascript
65new LicenseWebpackPlugin({
66 unacceptableLicenseTest: (licenseType) => (licenseType === 'GPL')
67});
68```
69
70* **`handleUnacceptableLicense`** - do something when an unacceptable license is found (default: disabled)
71
72Example:
73```javascript
74new LicenseWebpackPlugin({
75 unacceptableLicenseTest: (licenseType) => (licenseType === 'GPL'),
76 handleUnacceptableLicense: (packageName, licenseType) => {
77 // do something here
78 }
79});
80```
81
82* **`excludedPackageTest`** - exclude packages (default: disabled)
83
84Example:
85```javascript
86new LicenseWebpackPlugin({
87 excludedPackageTest: (packageName) => packageName === 'excluded-package'
88});
89```
90
91* **`perChunkOutput`** - control whether or not the license files are generated per chunk or are combined into one file (default: `true`)
92
93Example:
94```javascript
95new LicenseWebpackPlugin({
96 perChunkOutput: false // combine all license information into one file
97});
98```
99
100* **`addBanner`** - write a banner to the top of each js file (default: `false`)
101
102⚠️ **Webpack V5 Users**: Please read the notes on the `renderBanner` option as some special configuration is required when using banners on webpack v5.
103
104Example:
105```javascript
106new LicenseWebpackPlugin({
107 addBanner: true
108});
109```
110
111* **`licenseTypeOverrides`** - override the license type for specific packages (default: disabled)
112
113Example:
114```javascript
115new LicenseWebpackPlugin({
116 licenseTypeOverrides: {
117 foopkg: 'MIT'
118 }
119});
120```
121
122* **`licenseTextOverrides`** - override the license text for specific packages (default: disabled)
123
124Example:
125```javascript
126new LicenseWebpackPlugin({
127 licenseTextOverrides: {
128 foopkg: 'License text for foopkg'
129 }
130});
131```
132
133* **`licenseFileOverrides`** - override the license filename for specific packages (default: disabled)
134
135Example:
136```javascript
137new LicenseWebpackPlugin({
138 licenseFileOverrides: {
139 foopkg: 'The-License.txt'
140 }
141});
142```
143
144Notes: The license filename is resolved relative to the package directory.
145
146* **`renderLicenses`** - change the format / contents of the generated license file (default: print package name, license type, and license text)
147
148Example:
149```javascript
150new LicenseWebpackPlugin({
151 renderLicenses: (modules) => {
152 console.log(modules[0].packageJson, modules[0].licenseId, modules[0].licenseText);
153 return JSON.stringify(modules);
154 }
155});
156```
157
158* **`renderBanner`** - change the format / contents of the banner written to the top of each js file (default: print message indicating license filename)
159
160⚠️ **Webpack V5 Users**: The `modules` parameter to `renderBanner` will be empty in webpack v5 due to technical limitations. In addition, TerserPlugin (which is automatically enabled on production builds to minify code and extract licenses) will interfere with the banner. In order to turn off the license handling feature of TerserPlugin, it needs to be reconfigured in webpack configuration like this:
161
162```javascript
163const TerserPlugin = require('terser-webpack-plugin');
164
165module.exports = {
166 optimization: {
167 minimize: true,
168 minimizer: [
169 new TerserPlugin({
170 extractComments: false, // prevents TerserPlugin from extracting a [chunkName].js.LICENSE.txt file
171 terserOptions: {
172 format: {
173 // Tell terser to remove all comments except for the banner added via LicenseWebpackPlugin.
174 // This can be customized further to allow other types of comments to show up in the final js file as well.
175 // See the terser documentation for format.comments options for more details.
176 comments: (astNode, comment) => (comment.value.startsWith('! licenses are at '))
177 }
178 }
179 })
180 ]
181 }
182}
183```
184
185Example:
186```javascript
187new LicenseWebpackPlugin({
188 addBanner: true,
189 renderBanner: (filename, modules) => {
190 console.log(modules);
191 return '/*! licenses are at ' + filename + '*/';
192 }
193});
194```
195
196* **`handleMissingLicenseText`** - do something when license text is missing from a package (default: disabled)
197
198Example:
199```javascript
200new LicenseWebpackPlugin({
201 handleMissingLicenseText: (packageName, licenseType) => {
202 console.log('Cannot find license for ' + packageName);
203 return 'UNKNOWN';
204 }
205});
206```
207
208Notes: You can return your own license text from this function, but you should prefer using `licenseTextOverrides` first.
209
210
211* **`licenseTemplateDir`** - use fallback license files for when a package is missing a license file (default: disabled)
212
213Example:
214```javascript
215new LicenseWebpackPlugin({
216 licenseTemplateDir: path.resolve(__dirname, 'licenseTemplates')
217});
218```
219
220Notes: This option specifies a directory containing `.txt` files containing the license text based on the license type. (e.g. `MIT.txt`). Templates can be found [here](https://github.com/spdx/license-list).
221
222* **`chunkIncludeExcludeTest`** - control which chunks gets processed by the plugin (default: all chunks get processed)
223
224Example:
225```javascript
226new LicenseWebpackPlugin({
227 chunkIncludeExcludeTest: {
228 exclude: ['foo'],
229 include: ['bar']
230 }
231});
232```
233
234Example:
235```
236new LicenseWebpackPlugin({
237 chunkIncludeExcludeTest: (chunkName) => chunkName.startsWith('abc')
238});
239```
240
241Notes: If there is a duplicate entry in both the `exclude` and `include` array, the duplicated entry will be excluded.
242
243
244* **`modulesDirectories`** - limit which directories get scanned for license files (default: disabled)
245
246Example:
247```javascript
248new LicenseWebpackPlugin({
249 modulesDirectories: [
250 path.resolve(__dirname, 'node_modules')
251 ]
252});
253```
254
255* **`additionalChunkModules`** - add additional node modules to a chunk (default: disabled)
256
257Example:
258```javascript
259new LicenseWebpackPlugin({
260 additionalChunkModules: {
261 main: [
262 {
263 name: 'somepkg'
264 directory: path.join(__dirname, 'node_modules', 'somepkg')
265 }
266 ]
267 }
268});
269```
270
271* **`additionalModules`** - add additional node modules to the scan (default: disabled)
272
273Example:
274```javascript
275new LicenseWebpackPlugin({
276 additionalModules: [
277 {
278 name: 'somepkg'
279 directory: path.join(__dirname, 'node_modules', 'somepkg')
280 }
281 ]
282});
283```
284
285* **`preferredLicenseTypes`** - help the plugin decide which license type to pick in case a package specifies multiple licenses (default: disabled)
286
287Example:
288```javascript
289new LicenseWebpackPlugin({
290 preferredLicenseTypes: ['MIT', 'ISC']
291});
292```
293
294* **`handleLicenseAmbiguity`** - do something when the plugin finds ambiguous license types (default: pick first license type)
295
296Example:
297```javascript
298new LicenseWebpackPlugin({
299 handleLicenseAmbiguity: (packageName, licenses) => {
300 console.log(packageName);
301 console.log(licenses[0].url);
302 return licenses[0].type;
303 }
304});
305```
306
307Notes: This function is called whenever a license type could not be determined when a package uses the deprecated `licenses` field (which is an array of license types) in its package.json. It should return the license type to use. By default, the plugin prints a warning message to the console and chooses the first license type. You should use the `preferredLicenseTypes` option instead of this one.
308
309
310
311* **`handleMissingLicenseType`** - do something when a package is missing a license type (default: disabled)
312
313Example:
314```javascript
315new LicenseWebpackPlugin({
316 handleMissingLicenseType: (packageName) => {
317 console.log(packageName);
318 return null;
319 }
320});
321```
322
323Notes: You can return a license type from this function, but it is a better idea to use the `licenseTypeOverrides` option.
324
325* **`skipChildCompilers`** - do not apply the plugin to child webpack compilers (default: applies to child compilers too)
326
327Example:
328```javascript
329new LicenseWebpackPlugin({
330 skipChildCompilers: true
331});
332```