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 yarn or npm. npm stands for node package manager and is a way to manage dependencies through Node.js. Due to the advantages that yarn offers over npm, CoreMedia now recommends yarn for the frontend workspace. If you want to use npm make sure you read Section 5.16, “Using Npm Instead of Yarn”.

The Frontend Workspace is split into libs, config, themes and target. Please note, that config will not be created until running yarn 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.

yarn 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.

yarn build

Note

You need a stable internet connection to install the Frontend Workspace. Otherwise, dependencies cannot be downloaded from the yarn registry. You need at least access to https://registry.yarnpkg.com and github.com in order to build this workspace. Please check Section 5.14, “Running YARN Behind a Proxy Server” 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.

Alternative Installation via Maven

As a Java developer, you might be more familiar with Maven. You can also call Maven to build the frontend module. The Maven variant includes building all available themes and running all available tests.

mvn clean install

Note

Please note, that the installation via Maven is only available in the Blueprint workspace and won't work in a separated Frontend Workspace.

Consistent Dependency Versions For Installation

Package managers like Yarn 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 we are depending 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 we are fixating our 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 Yarn without any additional configuration. After each successful installation via yarn install a yarn.lock 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 Yarn will generate a new file with different (in most cases the most current) fixed versions.

Our releases also contain a single yarn.lock 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.