Getting started with front-end development

Magnolia supports two main approaches for building front-end applications:

Headless development using modern JavaScript frameworks like React, Angular, or Vue, with either client-side rendering or server-side rendering.
FreeMarker-based development for traditional server-side rendering using FreeMarker templates.

This guide walks you through setting up your environment and jumpstarting a project using the Magnolia CLI, whether you choose the headless or FreeMarker path.

Prerequisites and installation

Before you begin, make sure you have the necessary tools installed.

Get node.js

Magnolia CLI is an npm package providing a command line interface (CLI) tool to set up and facilitate light development with Magnolia. The Magnolia CLI tool runs on Node.js. If you do not have Node.js installed, go to Node.js and download and install the latest LTS version.

To check the version of your node installation, run the following command in a shell:

node -v

Get Java

Magnolia needs at least a Java Runtime Environment (JRE) to run. Check if there’s a version of Java already installed on your computer by opening the terminal or command prompt and typing java -version. If the system reports a version number, Java is installed on your computer.

See Certified stack to confirm that the version installed is supported.

For local development, use 17.0.12-zulu. Example installation using SDKMAN:

sdk install java 17.0.12-zulu

Windows
Mac
Linux

On Windows, you need a Java SE Development Kit (JDK). The Java Runtime Environment (JRE) is not enough because the Tomcat application server does not recognize it.

JRE is for users who run Java programs on their computers.
JDK is for developers who write Java-based applications.

Download and install JDK. By default, JDK is installed at C:\Program Files\Java\jdk-<version>\.

Instructions

Check for JAVA_HOME

Open the command prompt.
Type set and press ENTER.
Find JAVA_HOME in the command output and verify that the path points to your JDK installation directory, for example, C:\Program Files\Java\jdk-<version>>.xx.
If JAVA_HOME is missing or it points to the wrong directory, see Set JAVA_HOME.

Set JAVA_HOME

Open the Command Prompt as an administrator.
Set the path for JAVA_HOME.
```
setx /m JAVA_HOME "path\to\Java\jdk" (1)
```
1 Where path\to\Java\jdk is where your Java Development Kit is saved.

The set command creates the JAVA_HOME environment variable and sets its value to the JDK directory. The command is executed when Magnolia starts.

For Mac, you need to download or update to Java 25 or higher. After reviewing and agreeing to the terms of the license agreement, download the file, then double-click it to launch the installation wizard and follow the installation instructions.

The installation directory varies from one Linux system to another. On Debian-based distributions, JREs or JDKs are usually installed in /usr/lib/jvm/.

Using Magnolia CLI

We recommend using Magnolia CLI v5 to create and manage your front-end projects.

The CLI is a plugin-based tool that supports both FreeMarker and headless setups. It provides simple commands to build your project and manage its structure.

To simplify setup, install and run the CLI on a per-project basis. The CLI will take care of downloading and configuring everything for you.

Jumpstarting a Project

The jumpstart command is used for both FreeMarker and headless setups. It downloads the necessary Magnolia instance, configuration files, and optionally a front-end application based on your selection.

Using the jumpstart command

To begin, create a new directory and navigate into it:

mkdir magnolia-project
cd magnolia-project

Then run:

npx @magnolia/cli@latest jumpstart

You’re prompted to choose a project category and template.

The jumpstart command lets you create a Magnolia project with either:

A headless starter project and demo content
FreeMarker templates and demo content

Depending on your choice, continue with one of the following:

Feedback

DX Core