Developing and testing

Once you have set up a local Git repository and a local development, you are ready to start developing.

When adding new features to your local light-modules folder, always test them on your local Magnolia bundle before pushing them to the remote Git repository.

This page offers some insights about the development process itself such as writing the code to create new features for your Magnolia cloud package.


Develop with a running local instance

We recommend you develop with a running local Magnolia instance. Whenever you add a file to the light-module folder, Magnolia detects it and makes the file available to the system. In this way you can test and use your newly developed features directly.

Use the Definitions app and/or tail the log. Both display valuable information during code development, for example, whether your new items contain errors.

Add your code to the light-modules folder

We assume that you have already set up a local Git repository. When developing new features for your Magnolia cloud package, all code and all the resources must go into the light-modules folder of your local Git repository.

By introducing a new feature you expand an existing light module or create a new one.

Magnolia light modules

A Magnolia light module is a file and folder-based module. It can define every Magnolia item which can be configured in YAML – such as apps, content types, templates, dialogs, themes, and others. It can also contain a lightweight YAML-based module descriptor and web resources such as css and javascript files.

Light modules can be built with a simple text editor, with no special tools (such as Maven) required.

A light module cannot incorporate java classes.

Read Module structure to understand the folder and file structure of a Magnolia light module.

If you need to create a new light module, use the following Magnolia CLI command:

mgnl create-light-module <module-name>
Only use the characters from the [a-zA-Z0-9-_] regex range for the module name.

Use Magnolia CLI

Magnolia CLI is an npm package providing a command line interface (CLI) tool to set up and facilitate light development with Magnolia. It speeds up your work, helps avoid too many boilerplate tasks and is fun to use. Wondering whether you have already installed Magnolia CLI? Just open a shell, enter the following and press Return:

mgnl help
If you get mgnl: command not found, you should install Magnolia CLI.

The Magnolia CLI provides commands to create an empty light module, create a page and template components within a light module and other similar things. It creates all the necessary files (template definition, template script, dialog definition) and links them together on the basis of prototypes which you can modify per project or per light module. It is a powerful tool for agile development. Please note that Magnolia CLI is still under development and gets new features continuously. If you are familiar with it and have some cool ideas for new features it is lacking so far, please let us know by submitting a new idea with our Submit new idea form.

Build templates

Writing templates is a very common task when it comes to development. If you are completely new to templating, have a look at some of the following pages to learn the basics: Template definition, Dialog definition, Template scripts. Since the code of template scripts has to be written in FreeMarker, also see the Directives page explaining some of the most commonly used standard FreeMarker directives, as well as Magnolia-specific directives.

Built-in templating functions

Learn how to use the built-in templating functions. These functions can be used in FreeMarker scripts and provide methods to accomplish very common tasks that would be complicated to resolve with FreeMarker directives only.

  • cmsfn

  • damfn

  • sitefn

  • catfn

  • searchfn

  • restfn

  • resfn

  • imgfn

  • navfn

  • jsonfn

  • tagfn

Development tutorial for Magnolia in the cloud

Follow the Hello-cloud tutorial. It presents the complete Magnolia development cycle step-by-step based on a concrete example. In the tutorial you create a light module named hello-cloud on your local machine and bring it to your cloud-based Magnolia Live environment. All this with just a few clicks and in just a few minutes!


Testing should always be a part of your development process. In the context of local development, your goal should be to have error-free code before you push it to the remote Git repository. Test your code before you commit and push it with Git. Later on when your new code is in the cloud-based Magnolia package, test it again in the Integration environment before asking your editors and managers to do user acceptance testing in the UAT environment and finally going public in the Live environment.

Later, if you need to test new development work on the basis of real content that is already deployed in the UAT or Live environments, you can copy content from an environment for testing purposes.


Legacy Cloud



This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia Cloud docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules