Embed Widgets1 min read

Embed Widgets: Versioning & Breaking Changes

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

Docs  Embed Widgets  Versioning

Semantic versioning#

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

Patch (0.1.x)

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

Minor (0.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.

Pre-1.0 caveat

 WARNING

Until the SDK reaches 1.0.0 (after the remaining four widget bodies ship — see ), each minor release may carry incremental security hardening that is technically a breaking change. Pin to a specific version in production and watch the changelog. We'll call out any pre-1.0 breaking change prominently in the release notes.

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#

After v1.0 ships, 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": "0.1.0"
  }
}

Pre-1.0, use an exact version pin (no ^ or ~) so a routine npm install doesn't pick up an unintended minor. Post-1.0, switch to caret (^1.0.0) for automatic non-breaking updates.