Light modules

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.

Light module structure

The structure below was created using version 3.1.0 of the Magnolia CLI with the create-light-module command.

Light module structure example
└── foo/
    β”œβ”€β”€ apps
    β”œβ”€β”€ blocks
    β”œβ”€β”€ contentTypes
    β”œβ”€β”€ decorations
    β”œβ”€β”€ dialogs
    β”‚ β”œβ”€β”€ components
    β”‚ └── pages
    β”œβ”€β”€ i18n
    β”‚ └──
    β”œβ”€β”€ includes
    β”‚ └── README.txt
    β”œβ”€β”€ messageViews
    β”œβ”€β”€ restEndpoints
    β”œβ”€β”€ sites
    β”œβ”€β”€ templates
    β”‚ β”œβ”€β”€ components
    β”‚ └── pages
    β”œβ”€β”€ themes
    β”œβ”€β”€ virtualUriMappings
    └── webresources

Light modules folder

Magnolia light modules must reside within the Magnolia resources directory; this directory is also often referred to as the Magnolia light modules folder. The name and the location of this directory are arbitrary, but you must provide the path to the folder via configuration.

What is magnolia.resources.dir?

magnolia.resources.dir is a property defining the directory from which resources are loaded in a Magnolia instance. This directory is used for file-based resources such as light modules and for overriding classpath resources. The property is configured in WEB-INF/config/default/ and its default value is $magnolia.home/modules. To see the current value of the property, go to the Config Info tab in the About Magnolia app.

You can use symbolic links (symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.

Set the magnolia.resources.filesystem.observation.excludedDirectories property to exclude directories from being observed for changes. (See the table in the Configuration management: Defining properties section.)

A change in the light modules folder may also flush the server cache. You can configure this behavior under /modules/cache/config/contentCaching/defaultPageCache/flushPolicy/policies/lightModule/pathToCacheMappings/defaultPageCache with the pattern property, which specifies the pattern for the operation. The default value is ./(templates|webresources|i18n)/..

What items can be defined in a light module?

The following items can be defined within a light module using YAML. Items defined by YAML can be decorated, or can be reused with YAML inherit and include.

Non YAML-based items can also be used/found in light modules.

Creating a light module with Magnolia CLI

Using the Magnolia CLI introduction you can create the folder structure for a light module with the command create-light-module.

  1. Ensure you have Magnolia CLI introduction installed:

    mgnl -v

    You should see something similar to the following:

    Magnolia CLI: 3.1.1-snapshot (node.js: v12.18.1)
  1. Go to your light modules directory, and execute the following command:

    mgnl create-light-module <light-module>
When creating a name for a module, do not use spaces, accented characters such as Γ©, Γ , Γ§, Γ€, ΓΆ, ΓΌ or special characters (e.g.Β slashes /, \ and so on). The name must match the regular expression [a-zA-Z0-9-_].

DX Core



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

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.