UNPKG

13.6 kBMarkdownView Raw
1# rollup-plugin-license
2
3[![Greenkeeper badge](https://badges.greenkeeper.io/mjeanroy/rollup-plugin-license.svg)](https://greenkeeper.io/)
4[![Build Status](https://travis-ci.org/mjeanroy/rollup-plugin-license.svg?branch=master)](https://travis-ci.org/mjeanroy/rollup-plugin-license)
5[![Npm version](https://badge.fury.io/js/rollup-plugin-license.svg)](https://badge.fury.io/js/rollup-plugin-license)
6
7Rollup plugin that can be used to:
8- Prepend a banner from a file.
9- Create a file containing all third-parties used in the bundle (and display the license of each dependency).
10
11## How to use
12
13Install the plugin with NPM:
14
15```npm install --save-dev rollup-plugin-license```
16
17Then add it to your rollup configuration:
18
19```javascript
20const path = require('path');
21const license = require('rollup-plugin-license');
22
23module.exports = {
24 plugins: [
25 license({
26 sourcemap: true,
27 cwd: process.cwd(), // The default
28
29 banner: {
30 commentStyle: 'regular', // The default
31
32 content: {
33 file: path.join(__dirname, 'LICENSE'),
34 encoding: 'utf-8', // Default is utf-8
35 },
36
37 // Optional, may be an object or a function returning an object.
38 data() {
39 return {
40 foo: 'foo',
41 };
42 },
43 },
44
45 thirdParty: {
46 includePrivate: true, // Default is false.
47 includeSelf: true, // Default is false.
48 multipleVersions: true, // Default is false.
49 output: {
50 file: path.join(__dirname, 'dist', 'dependencies.txt'),
51 encoding: 'utf-8', // Default is utf-8.
52 },
53 },
54 }),
55 ],
56}
57```
58
59## Banner
60
61### Banner file
62
63The banner file can be a text file and it will be converted to a block comment automatically if needed.
64
65Note that the content will be translated to a lodash template with the following data model:
66- `pkg`: The content of the project `package.json`.
67- `dependencies`: An array of all the dependencies included in the bundle.
68- `moment`: The `moment` object.
69- `_`: The lodash object.
70- `data` A custom data object, defined in banner options.
71
72Here is a valid banner:
73
74```text
75Bundle of <%= pkg.name %>
76Generated: <%= moment().format('YYYY-MM-DD') %>
77Version: <%= pkg.version %>
78Dependencies:
79<% _.forEach(dependencies, function (dependency) { %>
80 <%= dependency.name %> -- <%= dependency.version %>
81<% }) %>
82```
83
84### Comment style
85
86Since version 0.10.0, it is possible to customize banner style using the `commentStyle` option:
87
88```javascript
89license({
90 banner: {
91 commentStyle: 'regular', // The default
92 content: {
93 file: path.join(__dirname, 'LICENSE'),
94 },
95 },
96})
97```
98
99Following options are available:
100
101- `regular`: "classic" comment block is used (this is the default), for example:
102
103```javascript
104/**
105 * This is the `regular` style.
106 */
107```
108
109- `ignored`: a comment block with prefix ignored by minifiers, for example:
110
111```javascript
112/*!
113 * This is the `ignored` style.
114 */
115```
116
117- `slash`: banner is prepended using "slash" comments, for example:
118
119```javascript
120//
121// This is the `slash` style.
122//
123```
124
125- `none`: nothing done, be careful to prepenbd a banner already "commented".
126
127### Banner as a "simple" string
128
129Since version 0.3.0, `banner` can be a simple string that will be used directly:
130
131```javascript
132const license = require('rollup-plugin-license');
133
134module.exports = {
135 plugins: [
136 license({
137 banner: `Copyright <%= moment().format('YYYY') %>`,
138 }),
139 ],
140}
141```
142
143If you want to add some options to banner (such as the comment style to use), and still define it as a `string` (insead of pointing to a file), you can also define the banner like this (since version `0.11.0`):
144
145```javascript
146const license = require('rollup-plugin-license');
147
148module.exports = {
149 plugins: [
150 license({
151 banner: {
152 content: `Copyright <%= moment().format('YYYY') %>`,
153 commentStyle: 'ignored',
154 },
155 }),
156 ],
157}
158```
159
160### Deprecated format
161
162Until version 0.10.0, banner file was defined as:
163
164
165```javascript
166const path = require('path');
167const license = require('rollup-plugin-license');
168
169module.exports = {
170 plugins: [
171 license({
172 banner: {
173 file: path.join(__dirname, 'LICENSE'),
174 encoding: 'utf-8',
175 },
176 }),
177 ],
178};
179```
180
181This format has been deprecated with version 0.11.0 and removed with version 1.0.O, and the banner file should be defined inside `banner.content` entry:
182
183```javascript
184const path = require('path');
185const license = require('rollup-plugin-license');
186
187module.exports = {
188 plugins: [
189 license({
190 banner: {
191 content: {
192 file: path.join(__dirname, 'LICENSE'),
193 encoding: 'utf-8',
194 },
195 },
196 }),
197 ],
198};
199```
200
201## Dependencies output
202
203A file containing a summary of all dependencies can be generated automatically using the following options:
204
205```javascript
206license({
207 thirdParty: {
208 output: path.join(__dirname, 'dist', 'dependencies.txt'),
209 includePrivate: true, // Default is false.
210 },
211})
212```
213
214Starting with version `0.12.0`, you can have more control by defining `output` as an object, for example:
215
216```javascript
217license({
218 thirdParty: {
219 includePrivate: false,
220 output: {
221 file: path.join(__dirname, 'dist', 'dependencies.txt'), // Path of the license report
222 encoding: 'utf-8', // default is UTF-8
223
224 // Template function that can be defined to customize report output
225 template(dependencies) {
226 return dependencies.map((dependency) => `${dependency.name}:${dependency.version} -- ${dependency.license}`).join('\n');
227 },
228 },
229 },
230})
231```
232
233Note that the template option can also be a lodash template:
234
235```javascript
236license({
237 thirdParty: {
238 includePrivate: false,
239 output: {
240 file: path.join(__dirname, 'dist', 'dependencies.txt'),
241
242 // Lodash template that can be defined to customize report output
243 template: `
244 <% _.forEach(dependencies, function (dependency) { %>
245 <%= dependency.name %>:<%= dependency.version%> -- <%= dependency.license %>
246 <% }) %>
247 `,
248 },
249 },
250})
251```
252
253For example, it can be relatively easy to produce a JSON output instead of a text file:
254
255```javascript
256license({
257 thirdParty: {
258 includePrivate: false,
259 output: {
260 file: path.join(__dirname, 'dist', 'dependencies.json'),
261 template(dependencies) {
262 return JSON.stringify(dependencies);
263 }
264 },
265 },
266})
267```
268
269By default, the "self" package is ignored (by "self", we mean the package being built), but startint with version 3.4.0, you can force inclusion using the `includeSelf` option:
270
271```javascript
272license({
273 thirdParty: {
274 includeSelf: true,
275 output: {
276 file: path.join(__dirname, 'dist', 'dependencies.json'),
277 template(dependencies) {
278 return JSON.stringify(dependencies);
279 }
280 },
281 },
282})
283```
284
285## License Checks
286
287Starting with version 0.13, it is possible to ensure that dependencies does not violate any license restriction.
288For example, suppose you want to limit dependencies with MIT or Apache-2.0 licenses, simply define the restriction such as:
289
290```javascript
291license({
292 thirdParty: {
293 allow: '(MIT OR Apache-2.0)',
294 },
295})
296```
297
298Note that the `allow` value here should be a valid SPDX pattern (more information [here](https://www.npmjs.com/package/spdx-expression-validate)).
299
300The `allow` option here will print a warning to the console for all license violation. Note that, if you want more control, it can also be defined as function:
301
302```javascript
303license({
304 thirdParty: {
305 allow(dependency) {
306 return dependency.license === 'MIT';
307 },
308 },
309})
310```
311
312The function defined here allow only MIT licenses, and will print a warning for anything else.
313
314Finally, if emitting a warning is not enought for you, you can also choose to fail the build:
315
316```javascript
317license({
318 thirdParty: {
319 allow: {
320 test: 'MIT', // Or a function that should returns `true` or `false`
321 failOnUnlicensed: true, // Fail if a dependency does not specify any licenses, default is `false`
322 failOnViolation: true, // Fail if a dependency specify a license that does not match given requirement, default is `false`
323 },
324 },
325})
326```
327
328Starting with version `3.1.0`, you can also use the `multipleVersions` option to track dependencies in different version as a different dependency.
329It can be particularly useful in case a dependency changed its license between two versions.
330
331Note that this option is `false` by default (mainly to keep backward compatibility).
332
333```javascript
334license({
335 thirdParty: {
336 includePrivate: false,
337 multipleVersions: true,
338 output: {
339 file: path.join(__dirname, 'dist', 'dependencies.txt'), // Path of the license report
340 encoding: 'utf-8', // default is UTF-8
341 template(dependencies) {
342 return dependencies.map((dependency) => `${dependency.name}:${dependency.version} -- ${dependency.license}`).join('\n');
343 },
344 },
345 },
346})
347```
348
349## Changelogs
350
351- 3.5.0
352 - Remove `mkidrp` dependency ([#1743](https://github.com/mjeanroy/rollup-plugin-license/pull/1743))
353 - Replace `glob` with `fdir` dependency ([#1742](https://github.com/mjeanroy/rollup-plugin-license/pull/1742))
354 - Dependency upgrades
355- 3.4.1
356 - Add the license for the package itself without having to specify `includePrivate` flag (see [comment](https://github.com/mjeanroy/rollup-plugin-license/issues/1685#issuecomment-2110103508)).
357- 3.4.0
358 - Allow adding the license for the package itself into the thirdParty output [#1685](https://github.com/mjeanroy/rollup-plugin-license/issues/1685)
359 - Dependency upgrades
360- 3.3.1
361 - Ensure the `multipleVersions` option is correctly validated ([#1682](https://github.com/mjeanroy/rollup-plugin-license/issues/1682))
362- 3.3.0
363 - Include notice file in the third party output ([#1683](https://github.com/mjeanroy/rollup-plugin-license/issues/1683))
364 - Dependency upgrades
365- 3.2.0
366 - Support rollup ^4.0.0
367 - Dependency upgrades
368- 3.1.0
369 - Add `thirdParty.multipleVersions` option ([#1528](https://github.com/mjeanroy/rollup-plugin-license/pull/1528))
370- 3.0.0
371 - Support rollup^3.0.0
372- 2.8.0
373 - Relax production dependency versions ([#1128]()https://github.com/mjeanroy/rollup-plugin-license/issues/1128)
374 - Update dependencies
375- 2.7.0
376 - Update dependencies ([#1077](https://github.com/mjeanroy/rollup-plugin-license/issues/1077))
377- 2.6.0
378 - Improve case insensitive search ([PR](https://github.com/mjeanroy/rollup-plugin-license/pull/931)), thanks [@codepunkt](https://github.com/codepunkt)!
379 - Search for `LICENCE` or `LICENSE` files ([PR](https://github.com/mjeanroy/rollup-plugin-license/pull/931)), thanks [@codepunkt](https://github.com/codepunkt)!
380- 2.5.0
381 - Look for dependencies' license files case insensitively, thanks [@Luke-zhang-04](https://github.com/Luke-zhang-04)!
382- 2.4.0
383 - Typings added
384 - Update dependencies
385- 2.0.0
386 - Support node >= 10
387 - Update dependencies
388- 1.0.0
389 - Remove support for rollup < 1.0.0
390 - Remove support for deprecated options.
391 - Support node >= 6
392- 0.14.0
393 - Update rollup peer dependency
394 - Produce a single file as dist output
395 - Update dependencies
396- 0.13.0
397 - Add license checking (see [#381](https://github.com/mjeanroy/rollup-plugin-license/issues/381)).
398- 0.12.1
399 - Restore compatibility with Node6
400- 0.12.0
401 - Improve `output` configuration (see [#379](https://github.com/mjeanroy/rollup-plugin-license/issues/379)).
402 - Improve option object validation and warning.
403 - Deprecate `thirdParty.encoding` option.
404 - Dev dependencies updates.
405- 0.11.0
406 - Fail if the banner file does not exist (breaking change).
407 - Deprecate `banner.file` / `banner.encoding` entries, use `banner.content.file` / `banner.content.encoding` instead (see [#428](https://github.com/mjeanroy/rollup-plugin-license/issues/428)).
408 - Allow comment style to be defined with a "string" banner (see [#308](https://github.com/mjeanroy/rollup-plugin-license/issues/308) and [#428](https://github.com/mjeanroy/rollup-plugin-license/issues/428)).
409 - Dev dependencies updates.
410- 0.10.0
411 - Support different comment style for banner (see [#308](https://github.com/mjeanroy/rollup-plugin-license/issues/308)).
412 - Do not include tree shaken dependencies (see [#380](https://github.com/mjeanroy/rollup-plugin-license/issues/380))
413 - Various dependency updates.
414- 0.9.0
415 - Fix for `NULL` character (see [#1](https://github.com/mjeanroy/rollup-plugin-license/issues/1)).
416 - Various dependency updates.
417- 0.8.1
418 - Add rollup as a peer dependency.
419- 0.8.0
420 - Deprecate `sourceMap` option (use `sourcemap` option in lowercase) to keep it consistent with rollup.
421 - Fix deprecate call with rollup >= 1, keep compatibility with legacy versions of rollup.
422 - Upgrade dependencies.
423- 0.7.0
424 - Add a way to specify custom data object when rendering banner.
425 - Add `cwd` option to specify custom working directory (optional option).
426 - Upgrade dependencies.
427- 0.6.0
428 - Upgrade `commenting` dependency.
429- 0.5.0
430 - Feat: Sourcemap is now enable by default to ensure compatibility with other rollup plugins.
431 - Fix: Add compatibility with rollup >= 0.48.0 (the new `sourcemap` option).
432 - Fix: Ensure plugin `sourcemp` is used instead of the "global" one in rollup options.
433 - Chore: dependency updates.
434- 0.4.0
435 - Dependency update (`moment`).
436 - Dependency update (`magic-string`).
437- 0.3.0
438 - Add encoding option for banner and third-party output file.
439 - Banner can be a simple string.
440
441## License
442
443MIT License (MIT)
444
445## Contributing
446
447If you find a bug or think about enhancement, feel free to contribute and submit an issue or a pull request.