Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bundle
✓ import { bundle } from 'camunda-schema-bundler';
✗ const bundle = require('camunda-schema-bundler');
The library primarily uses ESM. While CommonJS `require` might work with transpilers, direct ESM import is recommended. The `bundle` function is the main programmatic entry point for processing the schema.
BundleOptions
✓ import type { BundleOptions } from 'camunda-schema-bundler';
Use `type` import for `BundleOptions` to get type safety for the `bundle` function's configuration object. This package ships with TypeScript types.
cli
✓ import { cli } from 'camunda-schema-bundler';
While often used via the installed `camunda-schema-bundler` command, the CLI entry point can also be imported programmatically for integration into custom scripts or testing, though direct `bundle` function call is usually preferred for programmatic tasks.
This quickstart demonstrates programmatically invoking the `bundle` function to fetch the latest Camunda OpenAPI specification, process it, and output the bundled spec, metadata, and endpoint map files to a specified directory.
import { bundle } from 'camunda-schema-bundler';
import * as fs from 'node:fs/promises';
import * as path from 'node:path';
async function runBundler() {
const outputDir = path.join(process.cwd(), 'bundled-spec');
await fs.mkdir(outputDir, { recursive: true });
console.log('Starting Camunda schema bundling...');
try {
await bundle({
fetch: true, // Fetch the latest spec from GitHub (default: main branch)
outputSpec: path.join(outputDir, 'rest-api.bundle.json'),
outputMetadata: path.join(outputDir, 'spec-metadata.json'),
outputEndpointMap: path.join(outputDir, 'endpoint-map.json'),
ref: process.env.CAMUNDA_SCHEMA_REF ?? 'main', // Use 'main' or specify a tag/branch like 'stable/8.8'
repoUrl: process.env.CAMUNDA_SCHEMA_REPO ?? 'https://github.com/camunda/camunda-platform-7-rest-api',
});
console.log(`Bundling completed successfully. Output files generated in ${outputDir}`);
} catch (error) {
console.error('Error during bundling:', error);
process.exit(1);
}
}
runBundler();
camunda-schema-bundler --version
Debug
Known issues
breakingThe package requires Node.js version 18 or higher. Running with older Node.js versions will result in runtime errors or failures.fixEnsure your Node.js environment is updated to version 18 or newer. Use `nvm use 18` or update your system Node.js installation.
affects: <1.0.0 (engines field added/enforced)
gotchaOlder versions (prior to v1.3.3) had a bug (`fix deduplication leading to collapsed schemas`) that could result in incorrect or collapsed schemas in the bundled output, potentially leading to data loss or incorrect interpretations by downstream generators.fixUpgrade to `camunda-schema-bundler` version 1.3.3 or newer to ensure correct schema deduplication and bundling logic. This is a critical fix for data integrity.
affects: <1.3.3
gotchaWhen bundling for generators that expect path-local dereferenced schemas (e.g., C# / Microsoft.OpenApi), you must enable the `--deref-path-local` CLI option or its programmatic equivalent in the `bundle` function to avoid unresolvable references.fixIf generating code for C# or other strict OpenAPI parsers, ensure you use the `--deref-path-local` CLI flag or set `derefPathLocal: true` in the `BundleOptions` when calling `bundle` programmatically.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Node.js v16.x.x is not supported. Please use Node.js v18 or higher.
The package's `engines` constraint prevents it from running on Node.js versions older than 18.
fixUpgrade your Node.js environment to version 18 or higher. For example, using `nvm install 18 && nvm use 18`.
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax in an ES Module environment when `camunda-schema-bundler` is an ESM-first library.
fixChange your import statements to use ES Module syntax: `import { bundle } from 'camunda-schema-bundler';` Ensure your `package.json` has `"type": "module"` or your file uses `.mjs` extension. Error: Not found: https://github.com/camunda/camunda-platform-7-rest-api/tree/invalid-branch
The specified `--ref` (or `ref` in programmatic options) for fetching the upstream OpenAPI specification does not exist in the repository.
fixVerify the Git branch, tag, or SHA provided for `--ref` (or `ref`) is correct and exists in the target GitHub repository. Common issues include typos or using a deprecated branch name.
Audit
Dependencies
noderequiredRuntime environment for the npm package.