Module structure

Modular architecture

A Magnolia module can be purely file based or it can be wrapped in a Maven project.

  • Typical Maven Structure

  • Light module

Magnolia module wrapped in a typical Maven module structure before it is built.
    β”œβ”€β”€ pom.xml
    └── src/
        └── main/
            β”œβ”€β”€ java/
            └── resources/
                β”œβ”€β”€ META-INF/
                β”‚ └── magnolia/
                β”‚ └── module-name.xml
                └── <module-name>/
                    β”œβ”€β”€ apps/
                    β”œβ”€β”€ config.yaml
                    β”œβ”€β”€ dialogs/
                    β”‚ └── myDialog.yaml
                    β”œβ”€β”€ webresources/
                    └── templates/
                        β”œβ”€β”€ components/
                        β”‚ β”œβ”€β”€ myComponent.ftl
                        β”‚ └── myComponent.yaml
                        └── pages/
                            β”œβ”€β”€ myTemplate.ftl
                            └── myTemplate.yaml
File-based Magnolia module under $magnolia.resources.dir = Light module
└── <module-name>/
    β”œβ”€β”€ apps/
    β”œβ”€β”€ dialogs/
    β”‚ └── myDialog.yaml
    β”œβ”€β”€ module.yaml
    β”œβ”€β”€ webresources/
    └── templates/
        β”œβ”€β”€ components/
        β”‚ β”œβ”€β”€ myComponent.ftl
        β”‚ └── myComponent.yaml
        └── pages/
            β”œβ”€β”€ myTemplate.ftl
            └── myTemplate.yaml
These two folder trees show typical folder structures rather than structures with all folders possible.

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

The <module-name> folder contains exactly the same content in a Maven module and folder-based module. In a Maven module this folder is within src/main/resources. In a folder-based modules this folder is within $magnolia.resources.dir.

A module name must match the [a-zA-Z0-9-_] regular expression.

Reserved names

The following names cannot be used for a module name:





  • com.sun

  • gwt-unitCache

  • java

  • javax

  • jdk

  • lombok

  • oracle

  • org.apache

  • sun

Reserved characters

Do not use the following characters in a module name:

  • the space character

  • accented characters such as Γ©, Γ , Γ§, Γ€, ΓΆ, ΓΌ

  • special characters such as slashes /, \ and so on.

The create-light-module command in the Magnolia CLI creates the module folder structure on the file system automatically.

Module subfolders

Subfolder Description



Configuration data (YAML files) for apps.



Definition decorators (YAML files). Contains subfolders.



Dialogs (YAML files). May contain subfolders.



Field type definitions (YAML files) for Magnolia 5 UI.



i18n message bundles (.properties files).



Message view definitions (YAML files).



Renderer definitions.



REST endpoint definitions (YAML files) with subfolders.



Template definitions (YAML files) and scripts with subfolders.



Virtual URI mapping definitions (YAML files) to redirect incoming requests to actual content locations.



All web resources (typically contains subfolders). Folder name is arbitrary.

Definition item folders

A definition item is a component configuration for executing tasks in a Magnolia instance. Template definitions, dialog definitions, app definitions, renderer definitions, themes definitions,field definitions and REST endpoint definitions are all examples of such definition items.

The majority of these items can be configured via YAML, in which case they are registered in a specific registry. The items registered can be seen in the Definitions app. Even though definition items can be configured via JCR in the configuration workspace, configuring them in YAML files is the recommended approach.

The following folders host the definition items: apps, commands, dialogs, fieldTypes, messageViews, renderers, templates, traits, virtualURIMappings.

For more information see Module definition items.

Magnolia module specific files

Module descriptor

In a Magnolia file-based module (light module), the descriptor is located at $magnolia.resources.dir/example-light-module/module.yaml.

See YAML-based module descriptor more for information.
For Magnolia light modules, module descriptors currently support module dependencies only.

The config.yaml module configuration file

A Magnolia Maven-based module may contain the src/main/resources/<module-name>/config.yaml file. It contains configuration data, which is applied to the Java bean properties of the Magnolia module class.

See Module configuration for more information.

Light modules: file-based modules in $magnolia.resources.dir

You can add a file-based module in the $magnolia.resources.dir directory.

By default, $magnolia.resources.dir is the webapp folder (for example, magnoliaAuthor or magnoliaPublic).

See Installing a module for more information about $magnolia.home.

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-_].

Magnolia Maven module

If you are familiar with Java and Maven, you can use Maven to create and build your Magnolia module. Using Maven streamlines the process of creating a JAR file, deployment, and dependency management of your modules. All modules provided by Magnolia are built with Maven. This makes it easy to install or uninstall them by adding or removing a JAR file.

Creating a Magnolia Maven module with Maven archetypes

Magnolia provides a set of Maven archetypes for various tasks, one of which is creating a Magnolia Maven module.

Before running the Maven archetype command, please read How to use Magnolia Maven archetypes.

Executing the archetype plugin command

  1. Open a shell and change to the directory where you want the Magnolia Maven module skeleton to be created.

    cd /Users/jdoe/repositories/magnolia
  2. Run the following command:

    mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-module-archetype -DarchetypeVersion=RELEASE

Maven prompts you to specify values for several parameters. Use values that fit your requirements.

After you have finished entering the values, the archetype plugin displays their list and asks you to confirm it. If you confirm by pressing ENTER, the plugin generates the skeleton of your archetype. You should see a BUILD SUCCESS message at the end of the process. If you press N or CTRL + C, nothing is generated.


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.