SPA Integration Best Practices

This page outlines recommended practices for integrating a single-page application (SPA) with Bloomreach Content. These guidelines help front-end developers implement reliable integrations and ensure compatibility with Bloomreach support processes.

Use the SPA SDK

Use the SPA SDK to integrate your SPA with Bloomreach Content. The SDK reduces the amount of custom integration code you need to write and maintain. Bloomreach maintains the SDK and provides updates and bug fixes. If your SPA uses a JavaScript framework or version not supported by the SDK, consider forking the SDK and adapting it to your requirements. Maintain compatibility with the upstream SDK to benefit from future improvements.

Prevent Mixed Content Issues

Modern browsers block or warn about pages that load secure (HTTPS) and insecure (HTTP) content together. This issue often occurs in development environments if Bloomreach Content runs over HTTPS and your SPA runs over HTTP.

To avoid mixed content problems:

• Ensure your SPA uses HTTPS when your Bloomreach Content instance uses HTTPS.

Most frontend frameworks support HTTPS in development through configuration options:

• React
  Set the HTTPS=true environment variable. See Using HTTPS in Development for details.
• Angular
  Use the --ssl flag. See ng serve for details.
• Vue CLI
  Use the --https flag. See vue-cli-service serve for details.

Do not rely on browser settings to allow mixed content. This approach is not recommended.

Important: Always use HTTPS in production environments.

Deprecated Best Practices (14.0–14.1)

The following practices apply only if you are using brXM version 14.0 or 14.1 and the corresponding SDK.

Use the URL Rewriter for Reverse Proxying

In most implementations, the SPA is hosted separately from the Bloomreach Content instance. To enable preview and editing features in the Experience manager, the SPA must be accessible from the Experience manager's host. This requires server-side reverse proxying. Use the URL Rewriter enterprise plugin for this purpose. The plugin is available in Bloomreach Cloud environments. For setup instructions, see how to set up the URL Rewriter.

Use Absolute URLs for Static Resources

SPAs often reference static resources (such as icons or stylesheets) using host-relative paths like /images/icon.svg. These paths break when the SPA is served from the Experience manager's host. To ensure static resources load correctly in all scenarios, configure your SPA to use absolute URLs for all static resources.