Published adapters pin their Components release
Status: Accepted
Provenance: woksin made this decision on #233 on 2026-09-25. This record was written on 2026-09-29 to replace the peer range stated in Stable presentation renderer profile, which records the rest of the renderer contract and remains in force.
Context
Section titled “Context”Stable presentation renderer profile states that every adapter retains a @cratis/components >=4 <5 peer range. That range is what the adapter source manifests declare. The release pipeline has always published something else: scripts/prepare-release-version.mjs stamps every workspace peer with the release version, so each published adapter and Conformance release requires exactly the @cratis/components release it ships with. All 4.x releases are lockstep. #233 reported the contradiction and asked for one answer.
Decision
Section titled “Decision”Each published adapter (@cratis/components.primereact, @cratis/components.primereact10, @cratis/components.mui) and @cratis/components.conformance declares a peer on exactly the @cratis/components version it is released with. Applications install and upgrade an adapter and @cratis/components together, at the same version. The source manifests keep >=4 <5 as the bound the renderer ABI major allows. This replaces the peer range sentence in the semver policy of ADR 0004; the rest of that record is unchanged.
Options considered
Section titled “Options considered”- Publish the
>=4 <5range. Rejected for now: it lets an application install an adapter and a core release that were never released and tested together, while the renderer ABI is still new. - Pin the exact release. Chosen: every installable pair has been through the same release’s conformance run.
- Pin a caret range such as
^4.21.0. Rejected: it has the same untested-pair problem as the full range for every later minor release.
Default if unanswered
Section titled “Default if unanswered”The documented range and the published pin would keep contradicting each other. Readers of ADR 0004 would expect >=4 <5 and get peer-dependency errors on every Components upgrade that leaves the adapter behind.
Timeline and scope
Section titled “Timeline and scope”In force from 4.x onward. Revisit, with a new record, once the renderer ABI has stayed stable across several releases; widening then means stopping prepare-release-version.mjs from rewriting the adapter peers. The renderer ABI, the stable profile and the adapter certification rules in ADR 0004 are out of scope.
Verification
Section titled “Verification”Done when: Every published adapter and Conformance release declares a peer on exactly its own @cratis/components version, and the adapter and Conformance READMEs say so.
Verify by: npm view @cratis/components.mui@<version> peerDependencies (and the same for the other adapters and Conformance) shows "@cratis/components": "<version>".
Consequences
Section titled “Consequences”Every installable adapter and core pair was released and tested together. Applications upgrade the adapter and @cratis/components in lockstep on every release, including patch releases, and a peer-dependency error tells them when they have not. Widening the range later is a compatible change; narrowing it again would not be.