Preparing the Workspace

Before you can start developing your themes, you need to install the dependent node modules.

As a frontend developer, you are probably familiar with Node.js and pnpm or npm. npm stands for node package manager and is a way to manage dependencies through Node.js. Due to the advantages that pnpm offers over npm, CoreMedia now recommends pnpm for the frontend workspace.

The Frontend Workspace is split into libs, config, themes and target. Please note, that config will not be created until running pnpm start for the first time. See Section 4.1, “Structure of the Workspace” for more information.

Running the following script at the root level of the Frontend Workspace will install all necessary tools and dependencies. It will also automatically check for existing themes and will install their dependencies too.

pnpm install

Running the following script at the root level of the Frontend Workspace will automatically check for existing themes and will build them. Generated themes will be stored in target/themes as zip files.

pnpm build

Note

You need a stable internet connection to install the Frontend Workspace. Otherwise, dependencies cannot be downloaded from the npm registry. You need at least access to https://registry.npmjs.org/ and github.com in order to build this workspace. Please check Section 3.1, “Prerequisites” in Blueprint Developer Manual for more information on how to configure a proxy.

Some of our third-party dependencies (for example, node-sass) will attempt to compile binaries that could not be downloaded via github.com itself. If you see error messages like Error: Can't find Python executable "python", you can set the PYTHON env variable. this might be just an aftereffect because access to github.com was blocked. You do not need Python or any other compiler to install the frontend workspace.

Consistent Dependency Versions For Installation

Package managers like pnpm support Semantic Versioning when resolving dependencies. This means that dependencies can be specified using version ranges and usually the latest available version is installed. Making use of this feature has become common practice for most of the packages provided via these package managers. This includes packages the frontend workspace depends on. One of the intentions is to make upgrading to newer patches or minor versions easier without additional afford.

While in theory this seems to be a good agreement, relying on the assumption that a patch or minor upgrade will never break a running system has been proven wrong. This is why CoreMedia is fixating the used dependency versions to achieve consistent behavior across different installations (and builds) regardless of the time it is performed. So the same result is achieved no matter at which point of time the Frontend Workspace is being installed.

This is supported by pnpm without any additional configuration. After each successful installation via pnpm install a pnpm-lock.yaml file is generated (or updated) containing the used fixed versions. This file is meant to be checked in and should not be removed as otherwise the information will be lost and pnpm will generate a new file with different (in most cases the most current) fixed versions.

Our releases also contain a single pnpm-lock.yaml file in the root folder of the Frontend Workspace. Do not remove this file as it contains the dependency versions the Frontend Workspace release was tested with - so these versions are the dependency versions CoreMedia actually supports for that release. If the file is updated (for example, if you have added new dependencies) check in the updates to the version control.