Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@cyclonedx/webpack-plugin

CycloneDX90.2kApache-2.05.1.0TypeScript support: included

Creates CycloneDX Software Bill of Materials (SBoM) from webpack projects

webpack, CycloneDX, bill-of-materials, BOM, software-bill-of-materials, SBOM, inventory, component, dependency, package-url, PURL, SPDX

readme

CycloneDX webpack plugin

shield_npm-version shield_gh-workflow-test shield_coverage shield_ossf-best-practices shield_license
shield_website shield_slack shield_groups shield_twitter-follow


This plugin for webpack creates a CycloneDX Software Bill of Materials (SBoM) containing an aggregate of all bundled dependencies.
This is probably the most accurate, complete SBOM generator for webpack-based builds.

This plugin uses the linkages generated by webpack to create a dependency graph which only contain the dependencies that are actually used (after tree-shaking).

Requirements

  • Node.js >= 20.18
  • webpack ^5

However, there are older versions of this plugin, that support

  • Node.js v8.0.0 or higher
  • webpack v4.0.0 or higher

Installing

npm i -D @cyclonedx/webpack-plugin
yarn add -D @cyclonedx/webpack-plugin

Usage

new CycloneDxWebpackPlugin(options?: object)

Options & Configuration

Name Type Default Description
specVersion {string}
one of: "1.2", "1.3", "1.4", "1.5", "1.6"
"1.6" Which version of CycloneDX-spec to use.
Supported values depend on the installed dependency CycloneDX-javascript-library.
reproducibleResults {boolean} false Whether to go the extra mile and make the output reproducible.
Reproducibility might result in loss of time- and random-based-values.
validateResults {boolean} true Whether to validate the BOM result.
Validation is skipped, if requirements not met. Requires transitive optional dependencies.
outputLocation {string} "./cyclonedx" Path to write the output to. The path is relative to webpack's overall output path.
includeWellknown {boolean} true Whether to write the Wellknowns.
wellknownLocation {string} "./.well-known" Path to write the Wellknowns to. The path is relative to webpack's overall output path.
rootComponentAutodetect {boolean} true Whether to try auto-detection of the RootComponent.
Tries to find the nearest package.json and build a CycloneDX component from it, so it can be assigned to bom.metadata.component.
rootComponentType {string} "application" Set the RootComponent's type.
See the list of valid values. Supported values depend on CycloneDX-javascript-library's enum ComponentType.
rootComponentName optional {string} undefined If rootComponentAutodetect is disabled, then this value is assumed as the "name" of the package.json.
rootComponentVersion optional {string} undefined If rootComponentAutodetect is disabled, then this value is assumed as the "version" of the package.json.
rootComponentVCS optional {string} undefined If rootComponentAutodetect is disabled or the Version Control System is not declared in the package.json, then this value is used as the URL for RootComponent's External References' of type "vcs".
rootComponentBuildSystem optional {string} undefined Set the URL for RootComponent's External References' of type "build-system".
This behavior is regardless of rootComponentAutodetect's status.
collectEvidence {boolean} false Whether to collect (license) evidence and attach them to the resulting SBOM.

Example

In your webpack config add the CycloneDX plugin:

const { CycloneDxWebpackPlugin } = require('@cyclonedx/webpack-plugin');

/** @type {import('@cyclonedx/webpack-plugin').CycloneDxWebpackPluginOptions} */
const cycloneDxWebpackPluginOptions = {
  specVersion: '1.6',
  outputLocation: './bom'
}

module.exports = {
  // ...
  plugins: [
    new CycloneDxWebpackPlugin(cycloneDxWebpackPluginOptions)
  ]
}

See extended examples.

Support for IETF /.well-known/sbom

The CycloneDX webpack plugin supports placing the CycloneDX SBOM in a pre-defined location, specifically in /.well-known/sbom. This option is enabled by default. The behavior can be changed by overriding the values of includeWellknown and wellknownLocation.
See draft-ietf-opsawg-sbom-access for more information on the specification, currently an IETF draft.

In your webpack config add the CycloneDX plugin:

const { CycloneDxWebpackPlugin } = require('@cyclonedx/webpack-plugin');

/** @type {import('@cyclonedx/webpack-plugin').CycloneDxWebpackPluginOptions} */
const cycloneDxWebpackPluginOptions = {
  includeWellknown: true,
  wellknownLocation: './.well-known'
}

module.exports = {
  // ...
  plugins: [
    new CycloneDxWebpackPlugin(cycloneDxWebpackPluginOptions)
  ]
}

Use with Angular

Angular uses webpack under the hood. Therefore, it is possible to integrate this plugin by utilizing @angular-builders/custom-webpack.
See an example here: integration with Angular17/webpack5.

Use with React

React uses webpack under the hood. Therefore, it is possible to integrate this plugin.
See an example here: integration with React18/webpack5.

Internals

This webpack plugin utilizes the CycloneDX library to generate the actual data structures.

Besides the class CycloneDxWebpackPlugin and the interface CycloneDxWebpackPluginOptions,
this webpack plugin does not expose any additional public API or classes - all code is intended to be internal and might change without any notice during version upgrades.

Development & Contributing

Feel free to open issues, bugreports or pull requests.
See the CONTRIBUTING file for details.

License

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
See the LICENSE file for the full license.

changelog

Changelog

All notable changes to this project will be documented in this file.

unreleased

5.1.0 - 2025-06-16

  • Changed
    • Utilizes license file gatherer of @cyclonedx/cyclonedx-library, previously used own implementation (via #1398)
  • Dependencies
    • Upgraded runtime-dependency @cyclonedx/cyclonedx-library@^8.4.0, was @^8.0.0 (via #1398)
  • Build
    • Use TypeScript v5.8.3 now, was v5.8.2 (via #1382)

5.0.1 - 2025-03-17

Maintenance release

5.0.0 - 2025-03-17

  • BREAKING Changes
    • Dropped support for node<20.18.0 (#1362 via #1365)
  • Documentation
    • Fixed docs of default values (via #1369)
  • Dependencies
    • Upgraded runtime-dependency @cyclonedx/cyclonedx-library@^8.0.0, was @^7.0.0 (via #1367)
    • Upgraded runtime-dependency normalize-package-data@^7.0.0, was @^3||^4||^5||^6 (via #1368)
  • Build
    • Use TypeScript v5.8.2 now, was v5.7.3 (via #1376)

4.0.1 - 2025-01-29

  • Fixed
    • Prevent multiple, duplicate build-system entries (#1356 via #1355)

4.0.0 - 2025-01-27

  • BREAKING Changes
    • Option specVersion defaults to "1.6", was "1.4" (#1329 via #1333)
    • Emit $.metadata.tools as components (#1330 via #1331)
      This affects only CycloneDX spec-version 1.5 and later.
    • Emitted .purl values might be partially url-encoded (via #1331)
      This is caused by changes on underlying 3rd-party dependency packageurl-js.
  • Added
    • Emit "webpack" as part of $.metadata.tools (via #1354)
  • Dependencies
    • Upgraded runtime-dependency @cyclonedx/cyclonedx-library@^7.0.0, was @^6.11.0 (via #1331)
  • Build
    • Use TypeScript v5.7.3 now, was v5.6.3 (via #1351)

3.17.0 - 2025-01-10

  • Added
    • Configuration option for rootComponentVCS (#1344 via #1350)

3.16.0 - 2025-01-08

  • Added
    • Configuration option for rootComponentBuildSystem (#1344 via #1349)

3.15.1 - 2024-12-03

  • Fixed
    • Properly detect license evidences like LICEN[CS]E.{Apache,BSD,GPL,MIT} (#1337 via #1339)

3.15.0 - 2024-10-19

  • Added
    • Extended license evidence collection to also find *.LICEN[CS]E files (#1321 via #1322)
  • Build
    • Use TypeScript v5.6.3 now, was v5.6.2 (via #1320)

3.14.0 - 2024-10-08

  • Added
    • Feature for collecting (license) evidence (#676 via #1309, #1312)
      Controlled with option collectEvidence, disabled by default.
  • Build
    • Use TypeScript v5.6.2 now, was v5.5.3 (via #1302, #1306)

3.13.0 - 2024-07-21

  • Dependencies
    • Upgraded runtime-dependency @cyclonedx/cyclonedx-library@^6.11.0, was @^6.6.0 (via #1300)
      This was done to incorporate non-breaking upstream changes and fixes.
  • Build
    • Use TypeScript v5.5.3 now, was v5.4.5 (via #1296)

3.12.0 - 2024-06-17

  • Changed

3.11.0 - 2024-05-08

  • Added
    • Licenses acknowledgement might be populated (#1274 via #1281)
  • Misc
    • Raised dependency @cyclonedx/cyclonedx-library@^6.6.0, was @^6.5.0 (via #1281)

3.10.0 - 2024-04-23

Added support for CycloneDX Specification-1.6.

  • Changed
    • This tool supports CycloneDX Specification-1.6 now (via #1276)
  • Added
    • Option specVersion now supports value 1.6 to reflect CycloneDX Specification-1.6 (via #1276)
      Default value for that option is unchanged - still 1.4.
  • Build
    • Use TypeScript v5.4.5 now, was v5.4.2 (via #1270)

3.9.2 - 2024-03-19

  • Build
    • Use TypeScript v5.4.2 now, was v5.3.3 (via #1259)

3.9.1 - 2023-12-10

  • Fix
    • Malformed ingested package versions are fixed (via #1246)

3.9.0 - 2023-12-10

  • Changed
  • Build
    • Use TypeScript v5.3.3 now, was v5.3.2 (via #1244)

3.8.3 - 2023-12-01

  • Build
    • Use TypeScript v5.3.2 now, was v5.2.2 (via #1238)

3.8.2 - 2023-08-28

  • Build
    • Use TypeScript v5.2.2 now, was v5.1.6 (via #1218)
  • Misc
    • Raised dependency @cyclonedx/cyclonedx-library@^5||^6, was @^5 (via #1214)

3.8.1 - 2023-08-17

  • Misc
    • Raised dependency normalize-package-data@^3||^4||^5||^6, was @^3||^4||^5 (via #1194)

3.8.0 - 2023-08-17

  • Added
    • SBOM results are marked to be produced in lifecycle phase "build" (#1173 via #1188)
  • Misc
    • Raised dependency @cyclonedx/cyclonedx-library@^5, was @^3||^4 (via #1188)

3.7.0 - 2023-07-05

Added support for CycloneDX Specification-1.5.

  • Changed
    • This tool supports CycloneDX Specification-1.5 now (#1001 via #1021)
    • This tool warns now, if SBOM generation is skipped due to an unsupported value for option specVersion (via #1021)
      Previous behaviour was a silent skip.
  • Added
    • Option specVersion now supports value 1.5 to reflect CycloneDX Specification-1.5 (#1001 via #1021)
      Default value for that option is unchanged - still 1.4.
  • Build
    • Use TypeScript v5.1.6 now, was v5.1.3 (via #1017)
  • Misc
    • Raised dependency @cyclonedx/cyclonedx-library@^3||^4, was @^2.0.0 (#1001 via #1021)

3.6.1 - 2023-06-16

  • Build
    • Use TypeScript v5.1.3 now, was v5.0.4 (via #934)
    • Disabled TypeScript compilerOption esModuleInterop (via #892)
    • Disabled TypeScript compilerOption allowSyntheticDefaultImports (via #892)
  • Misc
    • Improved internal type-compatibility to webpack (via #980)

3.6.0 - 2023-05-17

  • Changes
    • SPDX license expression detection improved (via #881)
      Previously, some expressions were not properly detected, so they were marked as named-license in the SBOM results. They should be marked as expression, now.
  • Misc
    • Raised dependency @cyclonedx/cyclonedx-library@^2.0.0, was @^1.14.0 (via #881)

3.5.0 - 2023-04-27

  • Added
    • SBOM results might be validated (via #825)
      This feature is enabled per default and can be controlled via the new option validateResults.
      Validation is skipped, if requirements are not met. Requires transitive optional dependencies
  • Build
    • Use TypeScript v5.0.4 now, was v4.9.5 (via #790)

3.4.1 - 2023-03-31

  • Fixed
    • If packages' metadata normalization fails, then this results no longer in an unhandled crash but causes a warning message (#745 via #754)
  • Misc
    • Packages' metadata normalization is less verbose (via #754)
      If failed, then a warning is sent to webpack's log, now. No additional debug messages anymore.
      As always, you can control the display of these messages via webpack stats.

3.4.0 - 2023-03-28

  • Added
    • SBOM result might have serialNumber populated (#747 via #748)

3.3.1 - 2023-03-15

Maintenance release.

3.3.0 - 2023-03-02

  • Changed
    • Detected node packages' metadata are now normalized, before translation to SBOM components happens (#678 via #679)
      This might increase the quality of SBOM results.

3.2.0 - 2023-02-16

  • Added
    • SBOM result might have additional items in metadata.tools populated (#637 via #638)
  • Misc
    • Dropped outdated dependency read-pkg-up (#647 via #648)

3.1.4 - 2023-02-11

Maintenance release.

3.1.3 - 2022-12-16

Maintenance release.

3.1.2 - 2022-11-19

Maintenance release.

  • Build
    • Use TypeScript v4.9.3 now, was v4.8.3 (via #466)

3.1.1 - 2022-09-10

Maintenance release.

  • Misc
    • Style: imports are sorted, now (via #286)
  • Build
    • Use TypeScript v4.8.3 now, was v4.8.2 (via #288)

3.1.0 - 2022-09-07

  • Changed
    • PackageUrl(PURL) in JSON and XML results are as short as possible, but still precise (via #285)
  • Misc
    • Raised dependency @cyclonedx/cyclonedx-library@^1.4.0, was @^1.0.0 (via #285)
  • Build
    • Use TypeScript v4.8.2 now, was v4.7.4 (via #284)

3.0.1 - 2022-06-25

  • Docs
    • Added the configuration options to the README (via #75)

3.0.0 - 2022-06-20

This is a reboot, written in TypeScript and compiled to JavaScript.

  • BREAKING changes
    • Requires Node.js >= 14.0.0 now, was >= 12.0.0.
    • Requires webpack version ^5 as a peerDependency, was >=4 <6.
  • Changed
    • The optional configuration options changed in name and meaning. Consult the README for details.
  • Added
    • Added an optional switch to select the desired CycloneDX spec version for the output.
      The value currently defaults to '1.4' (fixes #53 via #70)
    • Full support for typing. This will make the configuration of this plugin easier.
    • Lots of small features got added due to the fact that the data processing is managed by @cyclonedx/cyclonedx-library now.
  • Fixed
    • Dependency graph no longer has null or undefined values (fixes #31 via #70)
  • Removed
    • The optional config option emitStats and its functionality were dropped. You may use webpack's --stats switch instead.
  • Misc
    • Uses @cyclonedx/cyclonedx-library now, instead of @cyclonedx/bom.

2.0.2 - 2022-06-11

  • Fixed
    • Fix invalid format of generated bom by incomplete package.json files in subdirectories of npm packages (#31 via #68)
  • Misc
    • Add integration test for react18 with webpack5 and babel-runtime dependency (via #68)

2.0.1 - 2022-05-05

  • Fixed
    • Fixed support for Webpack5 (#33,#47 via #55)
  • Misc
    • Removed dev-files from release package, like tests (via #54)
    • Fixed use of internals from foreign packages (via #60)

2.0.0 - 2022-04-24

  • BREAKING changes
    • Requires node >= 12.0.0 now, was 8.0.0 (via #51)
    • Requires webpack version >=4 as a peerDependency, like it was documented in the README (via #49)
  • Changed
    • Requires @cyclonedx/bom version^3.8.0 now, was ^3.1.1 (via #51)
  • Misc
    • Added reproducible test environments for unit an integration tests (via #51)
    • Applied coding standards (via #49)

1.0.2 - 2022-04-22

  • Fixed
    • data:-urls are no longer exported (#45 via #46)

1.0.1 - 2021-12-07

  • Fixed
    • Fixes related to bom-ref and internal flows.

1.0.0 - 2021-09-12

Initial release.