1 min read

Embed Widgets: Versioning & Breaking Changes

Semver discipline, loader URL pinning, breaking-change deprecation policy, and how to subscribe to release announcements.

Semantic versioning#

We follow Semantic Versioning. The major / minor / patch contract:

Patch (1.0.x)

Bug fixes only. No prop changes. No event changes. Safe to auto-update via npm.

Minor (1.x.0)

Additive — new widgets, new props, new events. Backward compatible. Existing code keeps working.

Major (x.0.0)

Breaking changes possible — but only after a 90-day deprecation period.

 INFO

The SDK is GA at 1.0.0 (all eight widgets shipped; the public API surface is frozen). Within the 1.x line, minor releases are additive and backward-compatible, so a caret range (^1.0.0) is safe. Breaking changes ship only in a new major, and only after the deprecation policy below.

Loader URL pinning#

The loader URL is pinned at /v1/ per FR-VER-1:

Stable loader URL

https://embed.aforo.ai/v1/loader.js

Within v1, the loader stays backward-compatible. When we ship v2, customers who haven't opted in keep getting the v1 loader. Opt-in to v2 by swapping the URL:

Future v2 (not shipped yet)

https://embed.aforo.ai/v2/loader.js

What counts as a breaking change#

A breaking change is anything that could cause customer code that worked on the previous version to stop working:

Change	Breaking?
Adding a new widget	No (minor)
Adding a new optional prop	No (minor)
Adding a new event type	No (minor)
Removing an event type	Yes (major)
Removing a prop	Yes (major)
Renaming a prop	Yes (major)
Changing a prop type (e.g. string → enum)	Yes (major)
Changing default behavior of an existing prop	Yes (major)
Changing the postMessage envelope shape	Yes (major)
Tightening CSP requirements	Yes (major)
Bumping React peer dependency minimum version	Yes (major)
Bumping SRI hashes (new build)	No (patch / minor) — customers re-pin from sri.json
Adding a new entry to the inbound event allowlist	No (minor)
Changing the iframe sandbox attribute	Likely (major) — could break parent integrations

90-day deprecation period#

Now that 1.0 has shipped, breaking changes follow this policy:

Day 0 — We announce the breaking change in CHANGELOG.md, the release notes, the docs portal, and (optionally) email. The deprecated prop / event keeps working with a runtime console warning.
Day 0-90 — Customers update their code at their own pace. The deprecated path keeps working.
Day 90+ — A new major version ships removing the deprecated path. The previous major continues to receive critical security patches for at least 12 months.

 INFO

Pre-launch exception (FR-QA-7). Until Aforo reaches its first paying customer using the embed tier, this 90-day rule is skipped — we may ship breaking changes in a single minor release to keep the development cycle tight. The rule reactivates the moment the first paying customer ships an integration. Watch the CHANGELOG for the activation announcement.

Subscribing to release announcements#

Three channels to stay informed:

CHANGELOG.md in the package — view on GitHub. Watch the repo for notifications on every release.
npm release notes — visible on the package page at npmjs.com/package/@aforoai/storefront-widgets.
Aforo changelog at aforo.ai/changelog — major releases also get a write-up here with migration guidance.

Pinning recommendations

package.json — recommended

{
  "dependencies": {
    "@aforoai/storefront-widgets": "^1.0.0"
  }
}

On the 1.x line, use a caret range (^1.0.0) so you pick up non-breaking minor and patch updates automatically — breaking changes only ever ship in a new major (2.0.0), and only after the deprecation period above. If you need a fully reproducible build, pin an exact version (e.g. 1.0.1) and bump it deliberately.