Get Started: Development Environment - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Get Started: Development Environment

Previous: Introduction - Next: Site Development

Out-of-the-box Account Setup

Out of the box, new brX accounts are set up with sample products and sample configuration which are used to validate the correctness of the account setup through a basic "Reference SPA". This out-of-the-box setup also helps account holders find a working system to start with, and it is intended to provide both regular users and developers with best-practices on how to set up and use brX.

The Reference SPA is not actually part of the brX account, it is hosted centrally by Bloomreach. When you access it inside the account’s Experience manager, the out-of-the-box configuration instructs the Experience manager to pass a pointer back to the account’s Delivery API's Pages endpoint to the Reference SPA, such that the Reference SPA will access the Delivery API of your brX account. When you run a copy of the Reference SPA locally, you’ll need to make sure to point it to your brX account’s Delivery API. The Reference SPA’s README contains instructions on how to accomplish this.

Because the Reference SPA is using your account’s Delivery API, you can already manage your content and page configuration in your brX account and observe the changes through the centrally hosted Reference SPA.

Local Frontend Development

An out-of-the-box working SPA is nice to start with but, ultimately, you want your brX account to power your experience. The first step to getting there is to obtain the code of the Reference SPA. You can do so by cloning the public git repository:

git clone https://github.com/bloomreach/bloomreach-reference-spa

The Reference SPA is a React-based, client-side rendered frontend. You can run the Reference SPA locally and start changing it, or you can use it as a reference implementation for your own "from scratch" frontend. If you choose to run the Reference SPA locally, follow the instructions in the project’s README file. The SPA is configured to run over HTTPS by default in order to make the integration with the brX back-end work.

The first time you start your local SPA, your browser may show a warning that the connection is not private and it may be unsafe to proceed. Since you are in full control of the application, you can ignore this warning and proceed.

The Reference SPA makes use of Bloomreach’s SPA SDK, which eases the use of the Content module’s Delivery API and helps with the integration of your frontend with the Experience Manager, such that brX users can manage aspects of the SPA in the Experience manager and see a preview of the effect of their changes.

While the SPA SDK eases the use of the Delivery API, as a developer you'll still want to understand the capabilities of the Delivery API in some detail.

You can access the Delivery API for the homepage of the sample “brxsaas” channel at this URL:

GET <your-brx-host>/delivery/site/v1/channels/brxsaas/pages

Developer Workspace

While changes to the frontend can be applied and tested in a local, safe setup, changes to the brX account are directly pushed into the cloud. In order to provide a safe way of developing, reviewing, and testing such "developer changes" (as opposed to changes made by regular brX users), the Content module makes use of the Projects feature.

We consider two categories of changes to be "developer changes", i.e. changes only users with Site Developer privileges are authorized to make: channel configuration changes and document type changes. Currently, multiple development projects can contain channel configuration changes but only one development project can contain document type changes.

Projects representing a developer workspace use the following workflow: Developers create a new development project in brX’s Projects app.

They can then associate the channel(s) they want to change with that project, in the Project’s Channels tab. Also there (clicking on the cogwheel icon), developers can set up the URL the Experience manager should load for that channel in the context of that development project. There is a URL for collaborating developers to share, and a URL for individual developers to use. The latter should typically point to a local URL.

If, after associating a local SPA with a development project, the Experience manager channel preview doesn't load or shows an error, you may need to open the SPA in a separate browser tab and explicitly ignore the warning that the connection is not private and may be unsafe. Since you are in full control of the application, it is safe to ignore the warning.

Once the channel is associated with the project, developers can push changes to that channel in the context of that project, using the Site Management API. The effect of these changes can be seen in the Experience manager, in the context of the developer project. You do so by navigating to the Experience manager by clicking on the channel entry in the Projects app.

Please note that, when accessing the local SPA outside of the Experience manager, the Delivery API will return the “live” page model, so you won’t be able to see changes to a development project there.

 

Previous: Introduction - Next: Site Development

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?