Below is an example of how to add the plugin to a webpack config:
const LicenseWebpackPlugin = require('license-webpack-plugin').LicenseWebpackPlugin; module.exports = { plugins: [ new LicenseWebpackPlugin() ] };
stats
- toggle warnings and errors on/off (default: report warnings and errors)Example:
new LicenseWebpackPlugin({ stats: { warnings: true, errors: true } });
licenseInclusionTest
- filter which licenses get included in the report (default: capture all licenses)Example:
new LicenseWebpackPlugin({ licenseInclusionTest: (licenseType) => (licenseType === 'MIT') });
Notes: 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
package. The plugin does not provide the spdx-satisfies
package, so you must install it separately if you want to use it.
Example using spdx-satisfies
:
const satisfies = require('spdx-satisfies'); new LicenseWebpackPlugin({ licenseInclusionTest: (licenseType) => satisfies(licenseType, '(ISC OR MIT)') });
outputFilename
- customize the license report filename (default: '[name].licenses.txt'
)Example:
new LicenseWebpackPlugin({ outputFilename: '[name].[hash].licenses.txt' });
unacceptableLicenseTest
- error out on unacceptable license (default: disabled)Example:
new LicenseWebpackPlugin({ unacceptableLicenseTest: (licenseType) => (licenseType === 'GPL') });
handleUnacceptableLicense
- do something when an unacceptable license is found (default: disabled)Example:
new LicenseWebpackPlugin({ unacceptableLicenseTest: (licenseType) => (licenseType === 'GPL'), handleUnacceptableLicense: (packageName, licenseType) => { // do something here } });
excludedPackageTest
- exclude packages (default: disabled)Example:
new LicenseWebpackPlugin({ excludedPackageTest: (packageName) => packageName === 'excluded-package' });
perChunkOutput
- control whether or not the license files are generated per chunk or are combined into one file (default: true
)Example:
new LicenseWebpackPlugin({ perChunkOutput: false // combine all license information into one file });
addBanner
- write a banner to the top of each js file (default: false
)Example:
new LicenseWebpackPlugin({ addBanner: true });
licenseTypeOverrides
- override the license type for specific packages (default: disabled)Example:
new LicenseWebpackPlugin({ licenseTypeOverrides: { foopkg: 'MIT' } });
licenseTextOverrides
- override the license text for specific packages (default: disabled)Example:
new LicenseWebpackPlugin({ licenseTextOverrides: { foopkg: 'License text for foopkg' } });
licenseFileOverrides
- override the license filename for specific packages (default: disabled)Example:
new LicenseWebpackPlugin({ licenseFileOverrides: { foopkg: 'The-License.txt' } });
Notes: The license filename is resolved relative to the package directory.
renderLicenses
- change the format / contents of the generated license file (default: print package name, license type, and license text)Example:
new LicenseWebpackPlugin({ renderLicenses: (modules) => { console.log(modules[0].packageJson, modules[0].licenseId, modules[0].licenseText); return JSON.stringify(modules); } });
renderBanner
- change the format / contents of the banner written to the top of each js file (default: print message indicating license filename)Example:
new LicenseWebpackPlugin({ addBanner: true, renderBanner: (filename, modules) => { console.log(modules); return '/*! licenses are at ' + filename + '*/'; } });
handleMissingLicenseText
- do something when license text is missing from a package (default: disabled)Example:
new LicenseWebpackPlugin({ handleMissingLicenseText: (packageName, licenseType) => { console.log('Cannot find license for ' + packageName); return 'UNKNOWN'; } });
Notes: You can return your own license text from this function, but you should prefer using licenseTextOverrides
first.
licenseTemplateDir
- use fallback license files for when a package is missing a license file (default: disabled)Example:
new LicenseWebpackPlugin({ licenseTemplateDir: path.resolve(__dirname, 'licenseTemplates') });
Notes: 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.
chunkIncludeExcludeTest
- control which chunks gets processed by the plugin (default: all chunks get processed)Example:
new LicenseWebpackPlugin({ chunkIncludeExcludeTest: { exclude: ['foo'], include: ['bar'] } });
Example:
new LicenseWebpackPlugin({ chunkIncludeExcludeTest: (chunkName) => chunkName.startsWith('abc') });
Notes: If there is a duplicate entry in both the exclude
and include
array, the duplicated entry will be excluded.
modulesDirectories
- limit which directories get scanned for license files (default: disabled)Example:
new LicenseWebpackPlugin({ modulesDirectories: [ path.resolve(__dirname, 'node_modules') ] });
additionalChunkModules
- add additional node modules to a chunk (default: disabled)Example:
new LicenseWebpackPlugin({ additionalChunkModules: { main: [ { name: 'somepkg' directory: path.join(__dirname, 'node_modules', 'somepkg') } ] } });
additionalModules
- add additional node modules to the scan (default: disabled)Example:
new LicenseWebpackPlugin({ additionalModules: [ { name: 'somepkg' directory: path.join(__dirname, 'node_modules', 'somepkg') } ] });
preferredLicenseTypes
- help the plugin decide which license type to pick in case a package specifies multiple licenses (default: disabled)Example:
new LicenseWebpackPlugin({ preferredLicenseTypes: ['MIT', 'ISC'] });
handleLicenseAmbiguity
- do something when the plugin finds ambiguous license types (default: pick first license type)Example:
new LicenseWebpackPlugin({ handleLicenseAmbiguity: (packageName, licenses) => { console.log(packageName); console.log(licenses[0].url); return licenses[0].type; } });
Notes: 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.
handleMissingLicenseType
- do something when a package is missing a license type (default: disabled)Example:
new LicenseWebpackPlugin({ handleMissingLicenseType: (packageName) => { console.log(packageName); return null; } });
Notes: You can return a license type from this function, but it is a better idea to use the licenseTypeOverides
option.