Magnolia has a modular architecture. A module can perform a task, package content, or provide specialized functionality. Modules can be project specific or they can be reused across different projects. You should use the module mechanism to package and deploy your own site's configuration and functionality.


Magnolia module

In Magnolia documentation, the terms module and project module always refer to a Magnolia module.

What makes a Magnolia module are files specific to Magnolia in a particular folder, see Module structure below. You can add such a Magnolia module folder directly into the webapp of your Magnolia instance. 

Best practice

When you are creating a website project, you should have one module for templates, another module for content, a third for a theme and so on.

Maven module

Maven also uses the term module but it means something different. When a Maven module is meant, we write Maven module. You can make the Magnolia module folder part of a Maven module. In that case you would build a JAR file and deploy it to your webapp.

All modules provided by Magnolia International are built with Maven. This makes it easy to install or uninstall them by adding or removing a JAR file.

Light module

You don't need to know Java or Maven to create a perfectly valid Magnolia module. Put your project files into a file-system directory to create a so-called light module. Use YAML-based configuration and Magnolia's unified resource loading.

This enables light development, a development style which does not require Java skills or a Java development environment. It's a straightforward way to get started with Magnolia development and works well for front-end developers. The Hello Magnolia tutorial uses light development to create a fully-functional template module.

It is best practice to store your light modules outside of the apache-tomcat directory so that the modules you add can be accessed by any Magnolia instance. If you already have a light modules directory you want to use, edit the magnolia.resources.dir property in your file to point to it.

Module structure

Magnolia module wrapped in a typical Maven module
structure before it is built.
File-based Magnolia module under $magnolia.resources.dir
Light module 
    ├── pom.xml
    └── src/
        └── main/
            ├── java/
            └── resources/
                ├── META-INF/
                │   └── magnolia/
                │       └── module-name.xml
                └── <module-name>/
                    ├── apps/
                    ├── dialogs/
                    │   └── myDialog.yaml
                    ├── webresources/
                    └── templates/
                        ├── components/
                        │   ├── myComponent.ftl
                        │   └── myComponent.yaml
                        └── pages/
                            ├── myTemplate.ftl
                            └── myTemplate.yaml


└── <module-name>/
    ├── apps/
    ├── dialogs/
    │   └── myDialog.yaml
    ├── module.yaml
    ├── webresources/
    └── templates/
        ├── components/
        │   ├── myComponent.ftl
        │   └── myComponent.yaml
        └── pages/
            ├── myTemplate.ftl
            └── myTemplate.yaml



The root folder of the module; the folder name is the name of the module.

(warning) For the name of the module use only the characters from the [a-zA-Z0-9-_] regex range.


Configuration data for apps (YAML files)

A Magnolia module can contain 0 to many apps.

dialogsDialogs (YAML files), may have subfolders
i18nA bundle of localization (*.properties) files
resourcesAll the resources, typically contains subfolders
templatesTemplate definitions (YAML files) and scripts with subfolders
themesTheme definitions (YAML files), may have subfolders.
module.yamlLight module descriptor.

Read Module structure for further imformation.

Using Maven and adding Java classes? Possible but not required

If you are familiar with Java and Maven you may want to use Maven to create and build your Magnolia module.

There is no requirement to use Java classes within a Magnolia module. But it is possible and offers many advantages. If you want to use Java classes, we recommend that you wrap your Magnolia module into a Maven module and add the classes to src/main/java.


Magnolia modules can define a couple of items as parts of the module. Such items are apps, fieldTypes, dialogs, commands, virtualURIMapping, templates. See Module structure above and Module configuration for further details.

If you are using Java and having a Module class, the module class can have bean properties which can be loaded at module startup with values from configuration data. 

Module descriptor

Maven-based Magnolia modules should provide a module descriptor.

 For file-based Magnolia modules (light modules) module descriptors currently only support module dependencies.

A module descriptor is a Magnolia-specific XML file that identifies and defines the module. When you start Magnolia, the system identifies available modules by locating each module's descriptor file.

The module descriptor file is located at src/main/resources/META-INF/magnolia/<module-name>.xml. This said, currently a module can only have a module descriptor when it is a Magnolia Maven module.

For further details please read XML-based module descriptor and YAML-based module descriptor.


#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels


  1. it's a best practice to have modules for each feature of my website? like splitting my webapp into many modules each module take care only of one business module?


    1. Hi Yassine

      I have no simple answer concerning the ideal degree of modularization.
      But I'm sure there is a lot of good books dealing with this topic.

      Personally I would not create a distinct module for every "feature" - I rather would unite a collection of features for the same "domain" within the same module.

      When it comes to a Magnolia Maven modules - compile time required dependencies to other modules also can indicate good module borders.