CycloneDX SBOM generator for esbuild

---

Create CycloneDX Software Bill of Materials (SBOM) from esbuild projects.

This package provides both an esbuild plugin and a CLI tool to generate CycloneDX SBOMs from your builds.

This tooling uses the linkages generated by esbuild to create an inventory which only contain the dependencies that are actually used (after tree-shaking).

Features

• 🔌 esbuild plugin for automatic SBOM generation during builds
• 🖥️ CLI tool for generating SBOMs from esbuild metafiles
• 🎯 Supports multiple CycloneDX spec versions (1.2, 1.3, 1.4, 1.5, 1.6, 1.7)
• 🔍 Extracts components and dependencies from bundled projects
• 📝 License evidence gathering
• ✅ Validates generated SBOMs against CycloneDX schema
• 🔄 Reproducible output option for consistent SBOM generation
• 📊 Works with TypeScript, Angular, and other modern frameworks

Requirements

• Node.js >= 20.18

Some features require optional (peer) dependencies — see package.json for version constraints.

• esbuild - required when using the plugin; not required for CLI-only usage
• ajv, ajv-formats & ajv-formats-draft2019 - required for SBOM JSON result validation

Installing

Use your preferred package manager and install as a dev-dependency:

npm install --save-dev @cyclonedx/cyclonedx-esbuild
pnpm add --save-dev @cyclonedx/cyclonedx-esbuild
yarn add --dev @cyclonedx/cyclonedx-esbuild

Usage

Esbuild Plugin

The esbuild plugin automatically generates an SBOM during your build process.

Esbuild Plugin Options & Configuration

Name	Type	Default	Description
specVersion	{string} one of: "1.2", "1.3", "1.4", "1.5", "1.6", "1.7"	"1.6"	Which version of [CycloneDX-spec] to use. Supported values depend on the installed dependency CycloneDX-javascript-library.
outputFile	{string}	"bom.json"	Path to the output file.
gatherLicenseTexts	{boolean}	false	Search for license files in components and include them as license evidence. This feature is experimental.
outputReproducible	{boolean}	false	Whether to go the extra mile and make the output reproducible. This requires more resources, and might result in loss of time- and random-based-values.
mcType	{string}	"application"	Set the MainComponent's type. See list of valid values.
validate	{boolean | undefined}	undefined	Validate resulting BOM before outputting. Validation is skipped, if requirements not met.

Esbuild Plugin Example

const esbuild = require('esbuild');
const { cyclonedxEsbuildPlugin } = require('@cyclonedx/cyclonedx-esbuild');

/** @type {import('@cyclonedx/cyclonedx-esbuild').CycloneDxEsbuildPluginOptions} */
const cyclonedxEsbuildPluginOptions = {
  specVersion: '1.7',
  outputFile: 'bom.json'
}

esbuild.build({
  // ...
  plugins: [
    cyclonedxEsbuildPlugin(cyclonedxEsbuildPluginOptions),
  ]
});

See extended examples.

CLI Tool

The Command Line Interface for generating SBOMs from esbuild metafiles.

CLI Call

Calling the CLI depends on the used install method.
Here are examples for the various package managers and setups:

npm exec -- cyclonedx-esbuild --help
pnpm exec cyclonedx-esbuild --help
yarn exec cyclonedx-esbuild --help

CLI Help Page

Usage: cyclonedx-esbuild [options] <metafile>

Create CycloneDX Software Bill of Materials (SBOM) from esbuild metafile.

Arguments:
  metafile                        Path to esbuild metafile

Options:
  --ewd, --esbuild-working-dir    Working dir used in the esbuild process.
  --gather-license-texts          Search for license files in components and include them as license evidence.
                                  This feature is experimental. 
                                  (default: false)
  --sv, --spec-version <version>  Which version of CycloneDX spec to use. 
                                  (choices: "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", default: "1.6")
  --output-reproducible           Whether to go the extra mile and make the output reproducible.
                                  This requires more resources, and might result in loss of time- and random-based-values. 
                                  (env: BOM_REPRODUCIBLE)
  -o, --output-file <file>        Path to the output file.
                                  Set to "-" to write to STDOUT.
                                  (default: write to STDOUT)
  --validate                      Validate resulting BOM before outputting.
                                  Validation is skipped, if requirements not met.
  --no-validate                   Disable validation of resulting BOM.
  --mc-type <type>                Type of the main component.
                                  (choices: "application", "firmware", "library", default: "application")
  -v, --verbose                   Increase the verbosity of messages.
                                  Use multiple times to increase the verbosity even more.
  -V, --version                   output the version number
  -h, --help                      display help for command

Use with Angular

For Angular projects using esbuild (Angular 17+), you can generate SBOMs from the build stats.

// package.json
{
  "scripts": {
    "build:app": "ng build --stats-json",
    "build:sbom": "cyclonedx-esbuild --gather-license-texts --output-reproducible -o dist/bom.json dist/stats.json",
    "build": "npm run build:app && npm run build:sbom"
  }
}

See an example here: integration with Angular20.

Internals

This tooling utilizes the CycloneDX library to generate the actual data structures.

Besides the class CycloneDxEsbuildPlugin and the interface CycloneDxEsbuildPluginOptions,
this esbuild plugin and this tool 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.

However, the CLI is stable - you may call it programmatically like:

const { execFileSync } = require('child_process')
const { constants: { MAX_LENGTH: BUFFER_MAX_LENGTH } } = require('buffer')
const sbom = JSON.parse(execFileSync(process.execPath, [
    '../path/to/this/package/bin/cyclonedx-esbuild-cli.js',
    '--spec-version', '1.7',
    '--output-file', '-'
    // additional CLI args
], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'buffer', maxBuffer: BUFFER_MAX_LENGTH }))

Development & Contributing

Feel free to open issues, bug reports 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.