Configure HST for SPA SDK

Info: This documentation applies to brXM 14.2.1 and later.

Overview

This page describes how to configure the Bloomreach Content delivery tier (HST) for integration with a Single Page Application (SPA) using the SPA SDK.

When to Use

Configure HST for SPA SDK integration when you want to:

Enable SPA frontends to consume content using the Delivery API.
Delegate page rendering from the Experience Manager to an external SPA.
Support cross-origin requests between the Experience Manager and your SPA.

You must use the Console to complete these configuration steps.

Prerequisites

brXM 14.2.1 or newer.
Access to the JCR Console.
The SPA SDK and Delivery API are available in your project.

Configuration Steps

1. Configure the Virtual Host for Delivery API and Cross-Origin Access

To enable the Delivery API for a virtual host:

Set the hst:pagemodelapi property to resourceapi on the relevant mount node.

To allow cross-origin requests from your SPA to the Delivery API:

Add a value such as Access-Control-Allow-Origin: https://www.example.com to the multi-valued hst:responseheaders property on the same mount node.
Replace https://www.example.com with the actual URL of your SPA.

Example configuration:

/hst:myproject/hst:hosts/dev-localhost/localhost:
  jcr:primaryType: hst:virtualhost
  /hst:root:
    jcr:primaryType: hst:mount
    hst:homepage: root
    hst:mountpoint: /hst:myproject/hst:sites/myproject
    hst:pagemodelapi: resourceapi
    hst:responseheaders: ['Access-Control-Allow-Origin: https://www.example.com']

Note: For advanced cross-origin configuration, such as supporting multiple origins, see Configure Delivery API (section "Configure CORS Response Headers").

2. Configure the Channel for Cross-Origin Resource Loading

To allow an external SPA to render a channel in the Experience manager:

Set the org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url property on the channel's hst:channelinfo node to the SPA's URL (for example, http://localhost:3000).

Example configuration:

/hst:myproject/hst:configurations/myproject/hst:workspace/hst:channel/hst:channelinfo:
  jcr:primaryType: hst:channelinfo
  org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url: http://localhost:3000

Preview URL Property Replacement

Info: Property replacement in the preview URL is supported starting with brXM 14.3.3.

You can use property placeholders in the org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url value. Placeholders are replaced with the values of matching system properties or HST configuration properties, in that order.

Example with placeholders:

http://${spa_url}?brxm=${pma_url}

If a placeholder cannot be resolved, the system returns a 404 error and logs a warning indicating the preview URL could not be parsed.

To avoid unresolved placeholders, you can specify default values:

${spa_url:http://localhost:3000}?brxm=${pma_url:http://localhost:8080/site/api/resourceapi}

If neither a system property nor an HST configuration property is set for spa_url or pma_url, the resolved value becomes:

http://localhost:3000?brxm=http://localhost:8080/site/api/resourceapi

Verification

Confirm that the Delivery API endpoint is accessible from your SPA.
Verify that cross-origin requests succeed from the SPA's domain.
In the Experience Manager, check that the channel preview loads content from the SPA as expected.