URL Rewriter Rules for Reverse-Proxying External SPA

In most SPA integrations with Bloomreach Experience Manager, the URL rewriter is necessary in order to implement reverse proxy functionality such that the SPA preview presented for editing in the Channel Manager is served on the same host as the CMS is served, while the SPA server is actually external to Bloomreach Experience Manager.

Install and Configure the URL Rewriter

Make sure to install the URL Rewriter plugin in your project, and use the following configuration parameters:

/hippo:configuration/hippo:modules/urlrewriter/hippo:moduleconfig:
  urlrewriter:ignorecontextpath: false
  urlrewriter:usequerystring: true

Furthermore, make sure that the urlrewriter:skippedprefixes property does contain the value _cmssessioncontext, but does not contain the value _cmsinternal.

Set up Reverse Proxy Rules

You need to set up a set of 3 rules for reverse-proxying the requests to your SPA server.

1. The first rule makes sure that the requests to the Page Model API are not proxied.
2. The second rule ensures that the request contains the query parameter bloomreach-preview=true for requests that pertain to the preview version.
3. The third rule actually proxies the request to the external SPA server.

Below rule set is intended for both client- and server-side rendered SPAs, should work locally and in production, both on Bloomreach Cloud and "on-premises".

Make sure to use the _cmsinternal infix, as opposed to the option described on this page.

Below rules do not cover static resources like JS and CSS bundles. Such bundles should be served from an external server, and accessed by the SPA through absolute URLs. The demo SPA implements a PUBLIC_URL environment variable, which it uses to generate these absolute URLs.

When applying the rules, you must adjust them to your specific situation:

• Replace http://localhost:3000 in the third rule with the location of your external SPA server.
• If your project uses a non-default prefix for exposing the Page Model API (as described here), you should replace resourceapi with your custom value in the first rule.
• If the channel hosting your SPA is mounted at a non-empty path below the hostname (e.g. http://www.example.com/channel-path), make sure to use the second set of rules, and replace spa-ssr with your channel path.

Rules for Empty Channel Path

If your channel path is empty (see previous bullet item), these are the rules to use:

<rule>
  <!-- Rule 1: Exclude requests for Page Model API and binaries -->
  <from>^(?:/[^\/]+)?(?:/_cmsinternal)?/(?:binaries|resourceapi|images)([\?/].*)?$</from>
  <to last="true">-</to>
</rule>

<rule>
  <!-- Rule 2: Ensure bloomreach-preview query parameter for preview requests -->
  <from>
    ^((?:/[^\/]+)?/_cmsinternal(?:/[^\?]*)?)(?:\?((?!(.*&amp;)?bloomreach-preview=.*).*))?$
  </from>
  <to type="redirect" last="true">$1?$2&amp;bloomreach-preview=true</to>
</rule>

<rule>
  <!-- Rule 3: Proxy requests to route to the SPA server -->
  <from>^(?:/[^\/]+)?(?:/_cmsinternal)?([\?/].*)?$</from>
  <to type="proxy" last="true">http://localhost:3000$1</to>
</rule>

Rules for Non-Empty Channel Path

If your channel path is non-empty (see previous bullet item), these are the rules to use. Remember to replace spa-ssr with your specific channel path.

<rule>
  <!-- Rule 1: Exclude requests for Page Model API -->
  <from>^(?:/[^\/]+)?(?:/_cmsinternal)?/spa-ssr/resourceapi([\?/].*)?$</from>
  <to last="true">-</to>
</rule>

<rule>
  <!-- Rule 2: Ensure bloomreach-preview query parameter for preview requests -->
  <from>
^((?:/[^\/]+)?/_cmsinternal/spa-ssr(?:/[^\?]*)?)(?:\?((?!(.*&amp;)?bloomreach-preview=.*).*))?$
  </from>
  <to type="redirect" last="true">$1?$2&amp;bloomreach-preview=true</to>
</rule>

<rule>
  <!-- Rule 3: Proxy requests to route to the SSR SPA -->
  <from>^(?:/[^\/]+)?(?:/_cmsinternal)?(?:/spa-ssr)([\?/].*)?$</from>
  <to type="proxy" last="true">http://localhost:3000$1</to>
</rule>