Skip to main content

Installation

In this section we will go through the prerequisites needed for Magnolia Headless Accelerator (HA).

To use Headless Accelerator you must install Node.js version 14 or higher, Java, Git, and Yarn on your device. If you have all of those already, go directly to the installation of Magnolia CLI.

1. Install Node.js#

To see if you already have Node.js installed and check the installed version, run the following commands:

node -v
info

The recommended version of Node is 16, unless you're using the project template with Magnolia and SFCC integration, in which case you need to use version 14.

If you don't have Node.js installed or it is not version 16 (or 14 for the SFCC project template), please follow these instructions.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bashexport NVM_DIR="$HOME/.nvm"[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completionnvm install 14nvm alias default 14

Node Version Manager (NVM) allows you to install and switch between multiple versions of Node.js and npm on your system.


2. Install Java#

You need to have Java installed on your system to run Magnolia. Make sure to use the version of Java supported by Magnolia. Check the the Magnolia Certified Stack for up-to-date information.

As of February 2022 supported versions of Java are Java 16 (supported by Magnolia 6.2.9+), Java 11 and Java 8.

Run this command to see the Java version installed:

java -version

If you do not have this setup already, please do the following:

Go to https://www.oracle.com/java/technologies/javase-jdk11-downloads.html, download according to your platform.

caution

Make sure you're using ARM compatible JDK when using Macbook M1 with the new Apple CPU.

info

Additionally, SDKMAN! can be used to install the specific version of Java required by Magnolia, providing easy Java version management.


3. Setup Git#

You can check if Git is installed on your device by running git --version. To configure your Git environment run:

git config --global user.name "My Name"git config --global user.email my.name@my-company.com

If you don't have Git installed, you can find the installation bundles here: https://git-scm.com/downloads.


4. Install Yarn#

If you haven't installed Yarn, run:

npm i -g yarn

5. Install Magnolia CLI#

The Headless Accelerator uses the Magnolia CLI to setup and facilitate light development with Magnolia. For more information visit Magnolia CLI documentation.

To install Magnolia CLI run this command:

npm i -g @magnolia/cli

You can check if Magnolia CLI is successfully installed by running command mgnl --version.


6. Install Headless Accelerator#

To install Headless Accelerator run:

npm install @magnolia/ha-cli -g

7. Install needed dependencies#

To install all needed dependencies, run:

ha

Headless Accelerator asks for the Nexus credentials, setups the .npmrc file in the users home directory and installs all needed dependencies.

warning

If you are encountering issues with installing the needed dependencies using the ha command, you need to set up the .npmrc file and install the dependencies manually. Please follow these steps to get everything up and running.

Now you can check the version of HA CLI by running ha --version. HA CLI should be the latest version.

Check the release notes to get more information about the current version.


Once this is done, you can use the full HA CLI functionality.

You will also have access to the @magnolia-dx and @magnolia-ea scope.

If you run HA in a CI Environment , you can copy your access token to MGNL_HA_AUTH_TOKEN environment variable. If the HA command finds this variable it will not prompt for username and password authentication.

info

Always make sure to have the latest version of the HA CLI. Update to the current version of the HA CLI if needed.


8. (Optional) Install Web components#

You can use UXF Web components to speed up your development process.

npm install @magnolia-ea/uxf-core

NOTE: Make sure you run the ha command (see step 6).


Congratulation!

You successfully installed all of the prerequisites.

Now you're ready to jumpstart your Headless project with Magnolia Headless Accelerator!


Troubleshooting#

Issue with Installing HA CLI Dependencies#

If you are encountering issues with installing the needed dependencies using the ha command, you need to set up the .npmrc file and install the dependencies manually. Please follow these steps to get everything up and running.

To install all needed dependencies, follow the steps below:

1. Set up the .npmrc file: You will need to manually configure the .npmrc file with the Nexus credentials. Replace <name> and <password> with your actual credentials and run the following commands:

echo "@magnolia-dx:registry=https://npm.magnolia-cms.com/repository/npm-enterprise/" >> ~/.npmrcecho "//npm.magnolia-cms.com/repository/npm-enterprise/:always-auth=true" >> ~/.npmrcecho "//npm.magnolia-cms.com/repository/npm-enterprise/:_auth=$(echo -n '<name>:<password>' | base64)" >> ~/.npmrcecho "@magnolia-ea:registry=https://npm.magnolia-cms.com/repository/npm-enterprise/" >> ~/.npmrc

2. Install the Magnolia DX HA CLI:

npm install -g @magnolia-dx/ha-cli

Mac users with Apple silicon#

If you encounter compatibility issues with specific x86-based Java applications, you may consider enabling Rosetta. Refer to Apple's documentation for instructions on enabling Rosetta if required.