Skip to content

Version your public contracts

Version public data-access exports — breaking changes ship as v2, not silent rewrites.

react-platform-version-public-contracts

Why it matters

Failure modes if this rule is ignored
StakeIf ignored
Hard to change
  • Without versioning, every change becomes a cross-team coordination project.
Breaking change
  • Breaking change to data-access without a version — consumers break with no migration path.

How to fix

The data-access lib of a domain is a contract. A breaking change to its public API = a new entry, not a delete of the old one. Consumers migrate at their own pace.

Examples

Bad
ts
// libs/sites-management/data-access/src/index.ts
// this week
export function getSite(id: string): Promise<Site>;
// next week — breaking change, no warning
export function getSite(id: string, options: GetSiteOptions): Promise<SiteWithMeta>;
Good
json
{
  "name": "@acme/sites-management-data-access",
  "exports": {
    ".":    "./src/index.ts",
    "./v1": "./src/v1/index.ts",
    "./v2": "./src/v2/index.ts"
  }
}

Contribute

Released under the MIT License.

esc