Development Guidelines

The Marketplace is an integral part of Magnolia’s product strategy and the single source of truth for the extensibility of our product. These guidelines for our Implementation Partners, Technology Partners and Developers, provide information on general technical aspects of developing extensions and will be updated regularly.


Developer guidance for how to build an external module

Light Dev integrations

  • Module structure 

  • Dependencies and versioning 


Java module integrations

  • Module structure 

  • Dependencies and versioning 

  • Configuration management (YAML vs JCR)

  • Logging

  • Security rights and roles


Module structure

Set correct BOM version 

Magnolia offers so-called BOM project for each Magnolia version so that external dependencies can rely on the same versions within various modules. Inherit the BOM version for your project which you target Magnolia version and use external dependencies as much as possible from that BOM project.

For instance, an example configuration is:



   <!--Dependency management section from external libs-->










And then for your external dependencies, you don’t need to specify a version as such:










Module descriptors


Archetype generator


Dependency injection




Recommend Password Manager module over YAML file for sensitive data


Roles and ACL (Access Control Lists)


Long-running actions/tasks



  • CVE scan beforehand 

  • Documentation

  • Definition app without any errors reported


Dependencies and versioning

Your module should support new installations as well as upgrades from previous versions of the module.

If your module depends on other Magnolia modules, you should define corresponding dependencies in the module definition. 

Clean dependency management is key for stable deployment. If your module relies on Magnolia modules then use the versions specified in the Magnolia bundle for your module dependencies.


Configuration management

Use YAML configurations wherever possible as it makes migrations and module deployment more efficient and manageable as version handlers are not required. 

Only use Yaml configurations for settings that are project-specific like endpoint URLs. 



Logging is an important part for stable operations, good logging practices will help system administrators, support providers and developers alike.

Your log messages should appropriate log levels to provide information to system administrators, support providers and developers:

  • Administrators -- providing detailed information lets them know if their Magnolia servers are running in perfect condition and alert them if there are problems, messages should use ERROR, FATAL and WARNING log levels

  • Support providers -- provide details and evidence to help resolve customer issues, usually WARNING and INFO log levels

  • Developers -- tracing code execution without attaching a debugger to shorten error troubleshooting, usually at DEBUG or TRACE log levels

Make sure that exceptions are logged in a self explanatory way.


Security rights and roles

Security is absolutely essential for every project. If your project requires custom roles then please ship them with your module and make sure that they are just granting access for the functionality needed for your app to function properly. 

Don’t apply added roles automatically to non-administrator groups. 

Document your roles clearly so the admin can decide which of your app roles are applied to user groups.

Become a Magnolia Marketplace partner

Complete the Marketplace inquiry form and get connected with us to bring your ideas to life.