Retrieving light modules

Finding light modules

Since all light modules are shared on npm, and include the keyword magnolia-light-module, they are easy to find:

If you have Magnolia CLI, use the mgnl search command.
Alternatively, visit: https://www.npmjs.com/search?q=magnolia-light-module

Because magnolia developers pay attention to good module design and README files, you can quickly see if there is a module that matches your requirements.

Getting light modules

There are several ways of getting light modules.

From npm

The packaged light modules on npm are ready to use.

If you have Magnolia CLI, use the mgnl install command.

Alternatively, you can use the command npm install <package name> in your terminal to install an npm package.

A few warnings will be printed because npm expects a package.json file in the directory where you run npm install.

The light module is downloaded into the node_modules directory. Move the light module into your Magnolia resources directory (aka light-modules), and delete the node_modules directory.

From Github

The npmjs.com search results also include links to the Github repository (or other source control repository). You can clone or download the light module source with the information provided there.

Github contains the complete light module project. Check the README file, it may be necessary to build the project to get or build the required web resources. By convention they can be built with npm run build in the terminal.

The project may contain other useful files, like tests and demos that you should not include in your production light module. Delete these files when you deploy the module to the Magnolia resources directory. This typically concerns the _dev and node_modules directories. You can check the .npmignore file for all things that do not belong in the `built' light module.

From an npm project

A benefit of having light modules on npm is that you can use its dependency resolution system to get all the modules you need into your project.

This can be useful in a Magnolia project based entirely on light modules. In the most basic version, you can define a package.json file which lists all of the light modules that you want. Anyone can then run npm install to retrieve all of the modules.

Please see this section on light projects for more information and some example projects hosted on github.

Through Maven

If you are a java developer, you can retrieve light modules in your Maven based java projects via the maven-frontend-plugin.

https://github.com/eirslett/frontend-maven-plugin

This plugin enables you to configure a complete, self-contained, front-end build environment and specify a package.json file with the desired light modules as dependencies.

Example Maven pom.xml

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-clean-plugin</artifactId>
      <configuration>
        <filesets>
          <!-- One directory, one fileset: -->
          <fileset>
            <!-- NPM will install all dependencies in 'node_modules' directory, thus we should add it to the
            clean phase -->
            <directory>node_modules</directory>
          </fileset>
          <fileset>
            <!-- The NPM build tools will copy the Magnolia light modules in there -->
            <directory>light-modules</directory>
          </fileset>
          <fileset>
            <!-- This will also clean the tmp directory of cargo install -->
            <directory>tmp</directory>
          </fileset>
        </filesets>
      </configuration>
    </plugin>
  </plugins>
</build>

<profiles>
  <profile>
    <id>get-light-modules</id>
    <build>
      <plugins>
        <plugin>
          <groupId>com.github.eirslett</groupId>
          <artifactId>frontend-maven-plugin</artifactId>
          <executions>
            <!-- First: install node and npm -->
            <execution>
              <id>install-node-and-npm</id>
              <goals>
                <goal>install-node-and-npm</goal>
              </goals>
              <configuration>
                <nodeVersion>v5.3.0</nodeVersion>
                <npmVersion>3.3.12</npmVersion>
                <!-- optional: where to install node and npm. Defaults to the working directory,
                 but we like it to be in target so that mvn clean removes the install again -->
                <installDirectory>target</installDirectory>
              </configuration>
            </execution>
            <!-- Second: install package.json (i.e. download all given light-modules) -->
            <execution>
              <id>npm-install</id>
              <goals>
                <goal>npm</goal>
              </goals>
              <!-- Optional configuration which provides for running any npm command -->
              <configuration>
                <arguments>install --registry=${npmRegistry}</arguments>
                <installDirectory>target</installDirectory>
              </configuration>
            </execution>
            <!-- Third: run the magnolia-build script to look for light modules in node_modules and copy them over
            light-modules -->
            <execution>
              <id>npm-build</id>
              <goals>
                <goal>npm</goal>
              </goals>
              <configuration>
                <arguments>run build</arguments>
                <installDirectory>target</installDirectory>
              </configuration>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Example package.json

{
  "name": "demo-maven",
  "version": "0.0.1t",
  "private": true,
  "description": "Grab light modules via Maven",
  "main": "index.js",
  "scripts": {
    "build": "magnolia-build"
  },
  "dependencies": {
    "calculator-magnolia": "latest"
  },
  "devDependencies": {
    "@magnolia/magnolia-build": "latest"
  }
}

Feedback

DX Core