feat!: give downstream users control over optional dependencies (#1295)

GauBen · jkowalleck · web-flow · commit 312add1b3547 · 2025-09-15T12:11:24.000+02:00
fixes #1294 --------- Signed-off-by: Gautier Ben Aïm <benaim.gautier@gmail.com> Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com> Co-authored-by: Jan Kowalleck <jan.kowalleck@gmail.com>
diff --git a/HISTORY.md b/HISTORY.md
@@ -6,6 +6,14 @@ All notable changes to this project will be documented in this file.
 
 <!-- add unreleased items here -->
 
+* BREAKING Changes
+  * Optional dependencies became optional peer dependencies (via [#1295])
+* Added
+  * Give downstream users control over optional dependencies ([#1294] via [#1295])
+
+[#1294]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/1294
+[#1295]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1295
+
 ## 8.6.0 -- 2025-09-09
 
 * Changed
diff --git a/README.md b/README.md
@@ -120,9 +120,9 @@ pnpm add github:CycloneDX/cyclonedx-javascript-library
 yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2
 ```
 
-## Optional Dependencies
+## Optional Peer Dependencies
 
-Some dependencies are optional.
+Some peer dependencies are optional.
 See the shipped `package.json` for version constraints.
 
 * Serialization to XML on _Node.js_ requires any of:
diff --git a/examples/node/javascript/.gitignore b/examples/node/javascript/.gitignore
@@ -3,3 +3,4 @@
 !/example.mjs
 !/example.cjs
 !/package.json
+!/.npmrc
diff --git a/examples/node/javascript/.npmrc b/examples/node/javascript/.npmrc
@@ -0,0 +1,5 @@
+; see the docs: https://docs.npmjs.com/cli/v11/using-npm/config
+
+; our lib has some peer deps that need to be installed.
+; due to how node module resolution works, we must not install the lib as a symlink!
+install-links=true
diff --git a/examples/node/javascript/package.json b/examples/node/javascript/package.json
@@ -5,5 +5,11 @@
   "dependencies": {
     "@cyclonedx/cyclonedx-library": "file:../../..",
     "xmlbuilder2": "^3.0.2"
+  },
+  "optionalDependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "ajv-formats-draft2019": "^1.6.1",
+    "libxmljs2": "^0.35||^0.37"
   }
 }
diff --git a/examples/node/typescript/example.cjs/.gitignore b/examples/node/typescript/example.cjs/.gitignore
@@ -1,6 +1,7 @@
 *
 !/.gitignore
 !/package.json
+!/.npmrc
 !/tsconfig.json
 !/src
 !/src/**
diff --git a/examples/node/typescript/example.cjs/.npmrc b/examples/node/typescript/example.cjs/.npmrc
@@ -0,0 +1,5 @@
+; see the docs: https://docs.npmjs.com/cli/v11/using-npm/config
+
+; our lib has some peer deps that need to be installed.
+; due to how node module resolution works, we must not install the lib as a symlink!
+install-links=true
diff --git a/examples/node/typescript/example.cjs/package.json b/examples/node/typescript/example.cjs/package.json
@@ -7,6 +7,12 @@
     "@cyclonedx/cyclonedx-library": "file:../../../..",
     "xmlbuilder2": "^3.0.2"
   },
+  "optionalDependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "ajv-formats-draft2019": "^1.6.1",
+    "libxmljs2": "^0.35||^0.37"
+  },
   "devDependencies": {
     "@types/node": "*",
     "typescript": "^3.8 || ^4 || ^5"
diff --git a/examples/node/typescript/example.mjs/.gitignore b/examples/node/typescript/example.mjs/.gitignore
@@ -1,5 +1,6 @@
 *
 !/.gitignore
+!/.npmrc
 !/package.json
 !/tsconfig.json
 !/src
diff --git a/examples/node/typescript/example.mjs/.npmrc b/examples/node/typescript/example.mjs/.npmrc
@@ -0,0 +1,5 @@
+; see the docs: https://docs.npmjs.com/cli/v11/using-npm/config
+
+; our lib has some peer deps that need to be installed.
+; due to how node module resolution works, we must not install the lib as a symlink!
+install-links=true
diff --git a/examples/node/typescript/example.mjs/package.json b/examples/node/typescript/example.mjs/package.json
@@ -10,6 +10,12 @@
     "@cyclonedx/cyclonedx-library": "file:../../../..",
     "xmlbuilder2": "^3.0.2"
   },
+  "optionalDependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "ajv-formats-draft2019": "^1.6.1",
+    "libxmljs2": "^0.35||^0.37"
+  },
   "devDependencies": {
     "@types/node": "*",
     "typescript": "^4 || ^5"
diff --git a/examples/web/parcel/.gitignore b/examples/web/parcel/.gitignore
@@ -1,5 +1,6 @@
 *
 !/.gitignore
 !/package.json
+!/.npmrc
 !/src/
 !/src/**
diff --git a/examples/web/parcel/.npmrc b/examples/web/parcel/.npmrc
@@ -0,0 +1,5 @@
+; see the docs: https://docs.npmjs.com/cli/v11/using-npm/config
+
+; our lib has some peer deps that need to be installed.
+; due to how node module resolution works, we must not install the lib as a symlink!
+install-links=true
diff --git a/examples/web/webpack/.gitignore b/examples/web/webpack/.gitignore
@@ -1,6 +1,7 @@
 *
 !/.gitignore
 !/package.json
+!/.npmrc
 !/webpack.json
 !/src/
 !/src/**
diff --git a/examples/web/webpack/.npmrc b/examples/web/webpack/.npmrc
@@ -0,0 +1,5 @@
+; see the docs: https://docs.npmjs.com/cli/v11/using-npm/config
+
+; our lib has some peer deps that need to be installed.
+; due to how node module resolution works, we must not install the lib as a symlink!
+install-links=true
diff --git a/package.json b/package.json
@@ -83,14 +83,36 @@
     "packageurl-js": "^2.0.1",
     "spdx-expression-parse": "^3.0.1 || ^4"
   },
-  "optionalDependencies": {
+  "peerDependencies": {
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
     "ajv-formats-draft2019": "^1.6.1",
     "libxmljs2": "^0.35||^0.37",
     "xmlbuilder2": "^3.0.2"
   },
+  "peerDependenciesMeta": {
+    "ajv": {
+      "optional": true
+    },
+    "ajv-formats": {
+      "optional": true
+    },
+    "ajv-formats-draft2019": {
+      "optional": true
+    },
+    "libxmljs2": {
+      "optional": true
+    },
+    "xmlbuilder2": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "ajv-formats-draft2019": "^1.6.1",
+    "libxmljs2": "^0.35||^0.37",
+    "xmlbuilder2": "^3.0.2",
     "@types/mocha": "^10",
     "@types/node": "ts5.7",
     "@types/spdx-expression-parse": "^3",

Original file line number	Diff line number	Diff line change
`@@ -5,5 +5,11 @@`
`5`	`5`	`"dependencies": {`
`6`	`6`	`"@cyclonedx/cyclonedx-library": "file:../../..",`
`7`	`7`	`"xmlbuilder2": "^3.0.2"`
	`8`	`+ },`
	`9`	`+ "optionalDependencies": {`
	`10`	`+ "ajv": "^8.12.0",`
	`11`	`+ "ajv-formats": "^3.0.1",`
	`12`	`+ "ajv-formats-draft2019": "^1.6.1",`
	`13`	`+ "libxmljs2": "^0.35\|\|^0.37"`
`8`	`14`	`}`
`9`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`*`
`2`	`2`	`!/.gitignore`
`3`	`3`	`!/package.json`
	`4`	`+!/.npmrc`
`4`	`5`	`!/tsconfig.json`
`5`	`6`	`!/src`
`6`	`7`	`!/src/**`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`*`
`2`	`2`	`!/.gitignore`
	`3`	`+!/.npmrc`
`3`	`4`	`!/package.json`
`4`	`5`	`!/tsconfig.json`
`5`	`6`	`!/src`