Migrating from 15.x.x to 16.x.x

New features

1. GraphQL support for V3 and V4 interfaces — GraphQL interactions can now be used with PactV3 and PactV4 (fixes #1093)
2. Asynchronous message support — V4 now supports asynchronous messages via addAsynchronousInteraction() (fixes #1186)
3. Synchronous message bodies — Bodies are now passed into the executeTest function for synchronous messages
4. Matching rules support — withMatchingRules is now available for HTTP, async, and sync interactions

Breaking changes

Import renames

The default Pact and Matchers exports have been changed to point to the V4 and V3 implementations respectively. The previous V2 implementations are still available under explicit names:

v15 export	v16 export	Notes
Pact	PactV2	The V2 HTTP Pact DSL
Matchers	MatchersV2	The V2 matchers
PactV4	Pact (alias)	The V4 Pact DSL is now the default
MatchersV3	Matchers (alias)	The V3 matchers are now the default

Note: PactV3 and MatchersV3 continue to be available as named exports — they are unchanged.

Node.js version

Node.js >=20 is now required. Versions 16–19 are no longer supported as they have reached end-of-life. If you cannot upgrade Node.js, remain on pact-js v15.

Downstream packages

The import renames above are known to impact packages that re-export or depend on the Pact / Matchers types:

• jest-pact
• nestjs-pact

Check for updated versions of these packages that are compatible with pact-js v16.

Migration guide

Consumer

Quick reference

If you currently import…	Action
Pact (V2 DSL)	Rename to PactV2 — required
Matchers (V2 matchers)	Rename to MatchersV2 — required
PactV4	Can be simplified to Pact — optional but recommended
MatchersV3	Can be simplified to Matchers — optional but recommended
PactV3	No changes needed

Upgrading to the V4 DSL (recommended)

If your imports already use the V4 interface:

import {
  SpecificationVersion,
  PactV4,
  LogLevel,
  MatchersV3,
} from '@pact-foundation/pact';

Simplify to:

import {
  SpecificationVersion,
  Pact,
  LogLevel,
  Matchers,
} from '@pact-foundation/pact';

No other code changes are needed — the API is identical.

Preserving V2 behaviour

If your imports use the V2 interface and you want to keep using it, you need to update the import names.

CommonJS:

// Before
const { Pact, Matchers } = require('@pact-foundation/pact');

// After
const { PactV2: Pact, MatchersV2: Matchers } = require('@pact-foundation/pact');

ES Modules:

// Before
import {
  Pact,
  GraphQLInteraction,
  Matchers,
  LogLevel,
} from '@pact-foundation/pact';

// After
import {
  PactV2 as Pact,
  GraphQLInteraction,
  MatchersV2 as Matchers,
  LogLevel,
} from '@pact-foundation/pact';

Provider

No changes are required for provider verification — the Verifier API is fully backwards compatible.