SPA SDKs - Lifecycle and Support
Introduction
The SPA SDKs are a collection of Javascript/Typescript artifacts maintained by Bloomreach product engineering. The collection consists of a framework-agnostic core SDK and a set of framework-specific extensions for the currently supported front-end frameworks:
Bloomreach develops this collection of artifacts using a single lifecycle: each release produces a new version (number) for all artifacts at once. The released artifacts expose a (JS) API, and have the following dependencies:
- Delivery API version(s) supported
- Front-end frameworks supported (see above)
- For each front-end framework-specific artifact, which range of versions of the framework is supported
There is also a dependency between the SDK and the Bloomreach Experience Manager in order to facilitate page management, based on the front-end displaying yet-to-be-published content. As this is a very stable API not intended for direct use, Bloomreach will only document the dependency once developers need to worry about it.
Customers of JS-based front-ends are expected to always use the core SDK, and optionally the framework-specific extension matching the framework of their choice. Customers are responsible for upgrading their front-end to use the latest SDK version, and they determine when this happens. In contrast, Bloomreach is responsible for upgrading the brX Content module (back-end), and Bloomreach is responsible for not breaking the compatibility between previous versions of the SDKs in use and the (new) back-end code.
The Delivery API is driving the managed content of the front-end. It is subject to relatively frequent updates and improvements. Quality control is in place to avoid accidentally rolling out non-backwards-compatible changes in undesirable ways.
Released SPA SDK artifacts are published on npmjs.org, and the SPA SDK code is published by mirroring its Git repository to GitHub.
Support, Dependencies, and Versions
Bloomreach maintains a single stream of SPA SDK releases which can be used for both the brX Content (SaaS) product and the brXM (on-premise or PaaS) product.
For each SPA SDK release, Bloomreach documents (in the release notes) which versions of the dependencies mentioned above are supported, i.e.
- Which major version(s) of the Delivery APIs are supported, both for the brX Content and the brXM product.
- Which front-end frameworks are supported, and for each of them,
- Against which version of that front-end framework the released artifact has been validated. This does not imply that customers cannot use the SDK in combination with a newer version of their framework (i.e. the SDK doesn’t “lock” the framework version), but it means that they will have to go through a validation effort themselves. Should they encounter any incompatibilities with the newer framework version, customers should reach out to Bloomreach Support to request support for the new framework version.
Bloomreach will support older major versions of the Delivery API for at least 1 year after a new major version of that API has been released, and Bloomreach will monitor usage of old APIs before phasing them out. Bloomreach may choose to remove support for an old Delivery API version from the SDK before or after that API version gets removed from the back-end service.
Bloomreach will make a reasonable effort to stay up-to-date with the most recent version of the supported front-end frameworks. Testing of new SPA SDK versions will happen against the latest supported framework version only. Bloomreach will be conservative and avoid that the SPA SDK unnecessarily depends on front-end framework features only available in new versions of the framework, such that the SDK remains compatible with a wide range of older versions of that framework.
If a new framework feature is adopted by the SPA SDK, the SPA SDK major version number is increased, and this backwards incompatible change is explicitly mentioned in the corresponding release notes.
Likewise, if any of the existing JS APIs (types, methods etc.) intended for use by the front-end are changed in a backwards incompatible way, i.e. upgrading to that version may require rework of the front-end beyond just increasing the dependency version number, the SPA SDK major version number is increased, and the backwards incompatible change is explicitly mentioned in the corresponding release notes.
If a customer has a requirement to stay on an older version of a front-end framework, but still make use of newer features of brX Content or brXM, they have the option to fork the SPA SDK code and make the necessary adjustments themselves. However, Bloomreach cannot support such custom variants of the SPA SDK artifacts, and recommends moving off such code forks as quickly as possible.