1 | # rollup-plugin-license
|
2 |
|
3 | [](https://greenkeeper.io/)
|
4 | [](https://travis-ci.org/mjeanroy/rollup-plugin-license)
|
5 | [](https://badge.fury.io/js/rollup-plugin-license)
|
6 |
|
7 | Rollup 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 |
|
13 | Install the plugin with NPM:
|
14 |
|
15 | ```npm install --save-dev rollup-plugin-license```
|
16 |
|
17 | Then add it to your rollup configuration:
|
18 |
|
19 | ```javascript
|
20 | const path = require('path');
|
21 | const license = require('rollup-plugin-license');
|
22 |
|
23 | module.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 |
|
63 | The banner file can be a text file and it will be converted to a block comment automatically if needed.
|
64 |
|
65 | Note 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 |
|
72 | Here is a valid banner:
|
73 |
|
74 | ```text
|
75 | Bundle of <%= pkg.name %>
|
76 | Generated: <%= moment().format('YYYY-MM-DD') %>
|
77 | Version: <%= pkg.version %>
|
78 | Dependencies:
|
79 | <% _.forEach(dependencies, function (dependency) { %>
|
80 | <%= dependency.name %> -- <%= dependency.version %>
|
81 | <% }) %>
|
82 | ```
|
83 |
|
84 | ### Comment style
|
85 |
|
86 | Since version 0.10.0, it is possible to customize banner style using the `commentStyle` option:
|
87 |
|
88 | ```javascript
|
89 | license({
|
90 | banner: {
|
91 | commentStyle: 'regular', // The default
|
92 | content: {
|
93 | file: path.join(__dirname, 'LICENSE'),
|
94 | },
|
95 | },
|
96 | })
|
97 | ```
|
98 |
|
99 | Following 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 |
|
129 | Since version 0.3.0, `banner` can be a simple string that will be used directly:
|
130 |
|
131 | ```javascript
|
132 | const license = require('rollup-plugin-license');
|
133 |
|
134 | module.exports = {
|
135 | plugins: [
|
136 | license({
|
137 | banner: `Copyright <%= moment().format('YYYY') %>`,
|
138 | }),
|
139 | ],
|
140 | }
|
141 | ```
|
142 |
|
143 | If 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
|
146 | const license = require('rollup-plugin-license');
|
147 |
|
148 | module.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 |
|
162 | Until version 0.10.0, banner file was defined as:
|
163 |
|
164 |
|
165 | ```javascript
|
166 | const path = require('path');
|
167 | const license = require('rollup-plugin-license');
|
168 |
|
169 | module.exports = {
|
170 | plugins: [
|
171 | license({
|
172 | banner: {
|
173 | file: path.join(__dirname, 'LICENSE'),
|
174 | encoding: 'utf-8',
|
175 | },
|
176 | }),
|
177 | ],
|
178 | };
|
179 | ```
|
180 |
|
181 | This 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
|
184 | const path = require('path');
|
185 | const license = require('rollup-plugin-license');
|
186 |
|
187 | module.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 |
|
203 | A file containing a summary of all dependencies can be generated automatically using the following options:
|
204 |
|
205 | ```javascript
|
206 | license({
|
207 | thirdParty: {
|
208 | output: path.join(__dirname, 'dist', 'dependencies.txt'),
|
209 | includePrivate: true, // Default is false.
|
210 | },
|
211 | })
|
212 | ```
|
213 |
|
214 | Starting with version `0.12.0`, you can have more control by defining `output` as an object, for example:
|
215 |
|
216 | ```javascript
|
217 | license({
|
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 |
|
233 | Note that the template option can also be a lodash template:
|
234 |
|
235 | ```javascript
|
236 | license({
|
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 |
|
253 | For example, it can be relatively easy to produce a JSON output instead of a text file:
|
254 |
|
255 | ```javascript
|
256 | license({
|
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 |
|
269 | By 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
|
272 | license({
|
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 |
|
287 | Starting with version 0.13, it is possible to ensure that dependencies does not violate any license restriction.
|
288 | For example, suppose you want to limit dependencies with MIT or Apache-2.0 licenses, simply define the restriction such as:
|
289 |
|
290 | ```javascript
|
291 | license({
|
292 | thirdParty: {
|
293 | allow: '(MIT OR Apache-2.0)',
|
294 | },
|
295 | })
|
296 | ```
|
297 |
|
298 | Note that the `allow` value here should be a valid SPDX pattern (more information [here](https://www.npmjs.com/package/spdx-expression-validate)).
|
299 |
|
300 | The `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
|
303 | license({
|
304 | thirdParty: {
|
305 | allow(dependency) {
|
306 | return dependency.license === 'MIT';
|
307 | },
|
308 | },
|
309 | })
|
310 | ```
|
311 |
|
312 | The function defined here allow only MIT licenses, and will print a warning for anything else.
|
313 |
|
314 | Finally, if emitting a warning is not enought for you, you can also choose to fail the build:
|
315 |
|
316 | ```javascript
|
317 | license({
|
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 |
|
328 | Starting with version `3.1.0`, you can also use the `multipleVersions` option to track dependencies in different version as a different dependency.
|
329 | It can be particularly useful in case a dependency changed its license between two versions.
|
330 |
|
331 | Note that this option is `false` by default (mainly to keep backward compatibility).
|
332 |
|
333 | ```javascript
|
334 | license({
|
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 |
|
443 | MIT License (MIT)
|
444 |
|
445 | ## Contributing
|
446 |
|
447 | If you find a bug or think about enhancement, feel free to contribute and submit an issue or a pull request.
|