CycloneDX SBOM generator for esbuild and Bun

Create CycloneDX Software Bill of Materials (SBOM) from projects built with esbuild or Bun.

This package provides:

• a plugin for esbuild-compatible bundlers — works with esbuild and Bun
• a CLI tool for generating SBOMs from esbuild-compatible build metafiles

The tooling uses the dependency linkage information generated during bundling to create an inventory and dependency graph (i.e., why a component is included in the final bundle).
Only dependencies that are actually included in the final bundle (after tree-shaking) are listed as such.

The resulting SBOM documents follow official specifications and standards, and might have properties following cdx:esbuild Namespace Taxonomy and cdx Namespace Taxonomy.

Features

• 🔌 Plugin for esbuild-compatible bundlers (esbuild, Bun)
• 🖥️ CLI tool for generating SBOMs from esbuild-compatible 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

One of the following runtimes:

• Node.js >= 20.18
• Bun >= 1.3.6

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

• esbuild — required when using the plugin with esbuild
• 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
bun add --dev @cyclonedx/cyclonedx-esbuild

Usage

Plugin Usage (esbuild and Bun)

The plugin works with esbuild-compatible bundlers.
Since Bun provides a plugin API compatible with esbuild, the same plugin can be used in both environments.

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. | | logLevel | {string \| undefined} | undefined | Controls the plugin's verbosity. Accepts the same values supported by esbuild's logLevel or the corresponding setting in Bun. If not set, the plugin inherits the logLevel from the build configuration. If that value is also undefined, it falls back to "warning". |

Plugin Example: esbuild

// build.js
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 example: integration with esbuild.

Plugin Example: Bun

Since Bun's plugin API is loosely based on esbuild's, this plugin can also be used in Bun projects that use the built-in bundler (Bun v1.3.6+).

// build.ts
import { cyclonedxEsbuildPlugin } from "@cyclonedx/cyclonedx-esbuild"

await Bun.build({
  // ...
  metafile: true, // required for `cyclonedxEsbuildPlugin` to work with Bun
  plugins: [
    cyclonedxEsbuildPlugin({
      outputFile: "bom.json",
      // ...
    }),
  ],
})

export {}

See example: integration with Bun.

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-compatible metafile.

Arguments:
  metafile                          Path to esbuild-compatible metafile

Options:
  --bwd, --build-working-dir <dir>  Working dir used in the build process.
                                    (default: current working dir)
  --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.