Open-sourcing a light module

When you are ready to share a light module with the greater Magnolia community, follow the instructions on this page.

Use a meaningful, findable name

The name of a shared module should be the same in magnolia, on npm and on github (or whichever public source code repository you use), and should work well in all of these contexts. We recommend the pattern <what-it-is>-magnolia .

For example: language-switcher-magnolia, chartjs-magnolia, pinterest-magnolia.

Use an appropriate location

Find an appropriate location on your hard drive for shared code.

  • If you are working with an existing light module from a project, copy or move the module out of the project to make it easier to maintain.

  • If you are creating a new module, use the Magnolia CLI npm run mgnl -- create-light-module <my-lm> command.

Symbolic links are a convenient way to have a shared light module in one location on your hard drive, but use it in many locations.

Open a terminal in your servers light-modules location and run:

ln -s <path to light module> <name of light module dir>

Example:

ln -s /Users/<jdoe>/Documents/shared-projects/chartjs-magnolia chartjs-magnolia

Test your light module

To ensure that your module works for others and contains everything it needs, we recommend you test it in a fresh Magnolia instance. To install a new instance, use the Magnolia CLI v5 npx @magnolia/cli jumpstart command.

Choose a license

Choose a license and add a license file to your light module.

We recommend the MIT license for modules that you are sharing publicly. This gives others freedom to use your module on any project.

Write a README.md

Good README files are key to the success of the Magnolia light module ecosystem. Someone looking for a module should understand yours quickly thanks to screenshots and clear descriptions in the README file.

We recommend you use this template: https://raw.githubusercontent.com/magnolia-cms/shareable-magnolia/master/README.md

Use Git

Initialize a Git repository in your light module directory. Code can be hosted in any publicly available repository, but we recommend GitHub due to its popularity and comprehensive feature set. If you create a https://github.com account, and create a repository via the website, it provides you with instructions on how to connect it to the project on your hard drive.

The npm init command will then automatically use the Git information.

Create a package.json file

Run the npm init command in your module directory. This prepares your module for distribution on npm by creating a package.json file. Accept the default prompts, but change the version to 0.0.1 unless you know you are ready for the first official release of your module.

Add npm Keywords

Once the package.json file is created, add the following keywords to the package.json to make it discoverable via search and to assist automation.

Keyword Description

magnolia-light-module

Required

magnolia-component

Optional

Use for a single component.

magnolia-kit

Optional

Use for a collection of templates.
Example
"keywords": [
    "magnolia-light-module",
    "magnolia-component"
  ],

Manage dependencies

Optionally, you can add a module.yaml file as the Magnolia module descriptor where you can specify any hard Magnolia dependencies. Specify this if your module uses a feature which became available in a certain version of Magnolia, such as decorations.

Example

https://raw.githubusercontent.com/magnolia-cms/shareable-magnolia/master/module.yaml

Clean up

Place all the files that you want to include in your GitHub source control project but that are not part of the actual light module, in the _dev directory.

.npmignore

While the source control project should include everything to help a developer use and understand your module, the published package on npm should be just a light-module that is ready to use in production. The .npmignore file is used by npm to exclude files from being published to npm. It should be configured to ignore the _dev directory.

Example

https://raw.githubusercontent.com/magnolia-cms/shareable-magnolia/master/.npmignore

Provide demo content

A demo page with one or more instances of the component delivered in the module can be very helpful for someone evaluating your module.

Export your demo page(s) to xml bootstrap files, and place them in _dev/demos. Describe how to access them in the Demo section of the readme.

  • Name your page: demo-<your module name>

  • You can use the mtk basic page template to host your component.

  • To load any necessary webresources on the sample page, you can add an HTML component on the page and include script and style tags in the HTML content.

Link to Java JARs

If your module depends on .jar files that are not in the standard Magnolia bundles, developers will need to install these files manually. We recommend that you include a link URL to any .jar files in the Usage section of the REAME file and explain how to install them. If you decide that you want to include the .jar files in your project, place them in _dev/jars.

Tips

Handling resources and JavaScript

We recommend:

  • Component templates typically should not contain script or stylesheet link tags to bring in web resource files. Developers who use your module must have control over how they want to include the web resources: using resfn, themes, static includes, require.js, and so on.

  • Component templates can include initialization JavaScript which relies on those libraries.

  • A component can be placed multiple times on the same page. It can help to have a unique id for each instance of the component. This can be created by using the id of the component node (FreeMarker expression: ${content.@id}).

Enabling customization

We recommend you provide a way for developers to customize how your module functions in their project. For example, the languageSwitcher component can be customized to render either a selection box or an unordered list by default.

You can use:

  • Template parameters - A developer can change the template parameters directly in the template definition, but this would mean they cannot use the npm package as-is. They need to edit the template definition. A cleaner practice would be to use a decoration in their own project module to modify the template definition.

  • Site parameters - This approach has the advantage that the component can be configured to behave differently on each site in a multi-site project.

Checklist

  • Directory Name Details <what it is>-magnolia

  • magnolia-light-module Details Keywords in package.json

  • Description Details In the README and the package.json

  • README Details Features, Usage, Demo

  • README screenshots

  • Small Details Your module provides one component, or a focussed set of functionality.

  • Demo

  • License file

  • Github Details Source code is available. (Or other public source control repository)

  • module.yaml

  • .npmignore Details To exclude the _dev directory and other things not relevant to a production light module.

  • Buildable Details Buildable with npm run build

Publish to npm

To publish your light module as a package to npm, run npm publish.

This interactive command also helps you setup a user on npm if you don’t yet have one.

View your published package at https://www.npmjs.com/package/<light module name>!

Your package can be found using npm search after a short time.

Let the world know

You are awesome. Thanks for contributing to the Magnolia community. Let everyone know by posting to the Magnolia User Mailing List. Mention @magnolia_cms in a tweet on twitter, and we’ll spread it to our followers. If you would like even more exposure, consider writing a personal blog post about it. You could even contact us to discuss hosting it on the magnolia blogs.

Next step

Want to learn about npm dependencies, front-end builds and light projects?

See Sharing modules - Advanced Frontend Topics.

Related topics
Feedback

DX Core

×

Location

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