This workspace contains the libraries that can be used to develop an SPA in combination with Bloomreach.
The SDKs are located under the packages folder and example SPAs are located in
the examples folder for each of the supported frameworks. See the READMEs of
the respective packages for more detailed information.
The SDKs:
The examples:
The latest SPA SDK versions support both the Paas and Saas backends from Bloomreach. For more information please read the latest developer guides on the documentation website.
The supported frameworks are currently:
The versions of these frameworks that the SDKs currently is verified to work
with are indicated in the release notes of each package and the minimum required
versions are set in the package.json files of the respective packages.
The integration between an SPA and Bloomreach Content is achieved by using a Framework SDK which itself has the SPA SDK as a dependency. Depending on the use case one might import interfaces or functions from the SPA SDK directly.
The SPA SDK itself is written in typescript and is framework independent, it holds the core code that sets up a connection to the Page Model API of the Bloomreach Content instance. When initializing it will use the provided configuration to do a call to the PMA and transform the response from a PageModel to a Page object that provides methods to easily query and work with the model. The SPA SDK also automatically detects whether it is in preview mode and sets up the connection with the Bloomreach Experience Manager Preview if that is the case. The Framework SDKs use this Page object to derive what needs to be rendered on the page.
In short the SPA SDK contains:
and the Framework SDK contains:
The repository contains multiple self-contained npm packages that also depend on other packages in the repository. To easily manage the dependencies between them and execute commands taking into account topological order, we use pnpm to manage its packages and builds.
This pnpm workspace configuration is located in the pnpm-workspace.yaml file.
Installation of the dependencies of all the workspaces is done by running pnpm install in the root of the workspace.
Running pnpm build will not only build all packages but also link them together such that you can develop packages locally without having to publish 'prerelease' versions.
Running pnpm dev in the root of the monorepo will watch each SDK package and build and link it when changes happen.
Combining this with running the dev server for one of the example apps allows for live development with any SDK.
You can use the pnpm CLI to run commands in a topological order. For example, to build a specific package and its dependencies, you can use:
pnpm --filter @bloomreach/example-react run build
This will build example-react as well as its dependency structure.
The root workspace commands are straightforward and are listed in the package.json scripts property.
There is the main branch which is protected and requires MR's to recieve
changes, it should only contain those changes/commits that are actually in a
released version of the SPA SDKs.
There is also the development branch which should be used as the baseline for
any other working branches.
Generally speaking for any kind of development one would:
development branch to a new branch e.g. mybranchmybranch until finishedmybranch to be merged into developmentnpm for test purposes and use dist-tag that mentions jira ticket or
general effort for easier recognition by running pnpm publish --filter <package-name> --tag [your Jira issue / effort name]developmentPre release actions:
development branch and make sure your local branch its up to date and the pipeline for development is greenpnpm docs can be done succesfullyRelease actions:
pnpm bump in the workspace root to update the versions in all package filesgit commit -am "[your Jira issue] Bumping versions to [new version]"development branch using git tag -a spa-sdk-[new-version]origin with git push --follow-tagsmain branch and merge it after approvePost release actions: