feat!: give downstream users control over optional dependencies

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

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:

examples/node/javascript/.gitignore

@@ -3,3 +3,4 @@
 !/example.mjs
 !/example.cjs
 !/package.json
+!/.npmrc

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

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

examples/node/typescript/example.cjs/.gitignore

@@ -1,6 +1,7 @@
 *
 !/.gitignore
 !/package.json
+!/.npmrc
 !/tsconfig.json
 !/src
 !/src/**

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

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"

examples/node/typescript/example.mjs/.gitignore

@@ -1,5 +1,6 @@
 *
 !/.gitignore
+!/.npmrc
 !/package.json
 !/tsconfig.json
 !/src

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

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"

examples/web/parcel/.gitignore

@@ -1,5 +1,6 @@
 *
 !/.gitignore
 !/package.json
+!/.npmrc
 !/src/
 !/src/**

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

examples/web/webpack/.gitignore

@@ -1,6 +1,7 @@
 *
 !/.gitignore
 !/package.json
+!/.npmrc
 !/webpack.json
 !/src/
 !/src/**

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

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",