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 . Only dependencies that are actually included in the final bundle (after tree-shaking) are listed.

The resulting SBOM documents follow official specifications and standards.

• 🔌 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

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

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

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.

// 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.

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.

The Command Line Interface for generating SBOMs from esbuild metafiles.

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

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

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.

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 }))

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

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