oasdiff-js

TypeScript/JavaScript wrapper for oasdiff - a Go CLI for comparing OpenAPI specifications.

Installation

npm install @oasdiff-js/oasdiff-js

yarn add @oasdiff-js/oasdiff-js

pnpm add @oasdiff-js/oasdiff-js

bun add @oasdiff-js/oasdiff-js

The correct oasdiff binary for your platform is installed automatically via an optional dependency (macOS, Linux, Windows).

Development

The upstream oasdiff version used by this repo is oasdiffVersion in package.json.

After changing it locally, sync the dev binary for your platform before running tests or examples:

bun run sync-binaries

Source code uses .oasdiff-bin/. Published packages use platform-specific optional dependencies instead.

Versioning model

Native packages (@oasdiff-js/oasdiff-*) are versioned to match the upstream oasdiff binary they contain. The main @oasdiff-js/oasdiff-js package follows its own semver and pins exact native versions in optionalDependencies.

Usage

Programmatic API

import {runOasdiffBreaking} from "@oasdiff-js/oasdiff-js";

const result = await runOasdiffBreaking("base.yaml", "revision.yaml");

console.log(result.changes);
// [{ id: "api-removed-without-deprecation", text: "...", level: 3, ... }]

From in-memory specs

import {runOasdiffBreakingFromSpecs} from "@oasdiff-js/oasdiff-js";

const result = await runOasdiffBreakingFromSpecs(baseSpec, revisionSpec);

API

Comparison commands

Each has a *FromSpecs variant that accepts objects instead of file paths.

Checks

import {runOasdiffChecks} from "@oasdiff-js/oasdiff-js";

const {checks} = await runOasdiffChecks();

Options

All comparison functions accept options for format, filtering, flattening, deprecation rules, etc:

await runOasdiffBreaking("base.yaml", "revision.yaml", {
  format: "json",
  failOn: "ERR",
  includeChecks: ["check-id"],
  flattenAllOf: true,
});

Result shape

interface IOasdiffRunResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}

// Breaking and changelog also include:
interface IOasdiffBreakingResult extends IOasdiffRunResult {
  changes: IOasdiffChange[];
}

CLI

The package installs an oasdiff binary that you can use directly:

npx oasdiff breaking base.yaml revision.yaml

bunx oasdiff breaking base.yaml revision.yaml

For the full CLI reference, see the oasdiff documentation.

Troubleshooting

Binary not found after install

If the platform-specific optional dependency was not installed, the binary will be missing. This can happen when:

• Optional dependencies are disabled: some CI environments or lockfile generators skip optional dependencies
• Unsupported platform: your OS or architecture does not have a prebuilt binary

Reinstall with optional dependencies

rm -rf node_modules package-lock.json
npm install

For pnpm:

rm -rf node_modules pnpm-lock.yaml
pnpm install

For bun:

rm -rf node_modules bun.lock
bun install

Other environments

If the above does not work, you can also download the correct binary manually from the oasdiff releases page and pass its path to the programmatic API via the binaryPath option.

License

Apache-2.0