Modern front-end development with Magnolia and Frog Rain

Published on March 16, 2017 by Niko Salminen

Frog Rain is a semi-opinionated starter project for Magnolia front-end development. It provides a way to structure your light module files and the tools to build a working module using the latest and greatest front-end development tools and best practices.

Light modules, introduced in Magnolia 5.4, were an incredible leap forward in enabling fast and agile front-end development for Magnolia projects. That being said, it took us quite a while to set up our build process to allow it to cater to both our needs and the required structure of a light module. The site we were building was huge and contained a lot of variation so we needed lots and lots of components.

A common approach to working with multiple components that require JavaScript functionality is to keep each of them in their own .js files. The result is then concatenated and optimized (also known as “uglified”) into one large scripts.js file. This worked fine when we had ten components. However it started to become a problem when we had 40 components. The file was becoming large and most of it was functionality for components that weren’t even on the page. We were using less than ten components on any given page so 75% of the downloaded JS package was dead weight. All of the components had some checks to determine whether they needed to be initialized, so that slowed down our site rendering as well. And we didn’t stop at 40 - we currently have 112 components on the site.

After a few weeks of experimenting, we came up with a directory structure that suited our needs. It closely mimics the structure of a light module but also keeps the CSS and JS source files in the same directory as the component they are related to. We set up gulp to compile them into a ready-to-use light module right inside the developer’s locally running Magnolia’s resource directory.

We also wrote our own library called PPR.js to tackle the problem with unnecessary JavaScript being sent to the user. It scans the page for components that need to run JS and downloads their script files on demand using require.js.

Our new directory structure proved to be logical and fast to work with. Our gulp build script executes in less than a second so any changes made to the source files are visible almost immediately. Our toolset also allows us to use modern languages, removing the need to worry about browser compatibility. Splitting the JavaScripts to smaller chunks removed a lot of unnecessary network and performance overhead. It also gave us a way to write code that runs in the scope of each instance of a component: it enables multiple instances of a component on any page without conflicts.

What is included

The heart of Frog Rain is a set of gulp scripts that build the project files. There are separate tasks for copying the templates, definitions and dialogs to their correct directories in the target light module, but the scripts doing the most work are the ones that create the JavaScript and CSS files.

  • The stack that handles CSS generation looks like this:
  • SCSS, the industry standard CSS extension
  • Sass-globbing allows using wildcards in SCSS imports
  • PostCSS for running autoprefixer to take care of vendor prefixing

The JavaScript stack has a bit more going on:

  • Babel for transpiling ES2015 code to browser compatible ES5 JavaScript
  • Uglify for minimizing the size of the produced files
  • ESLint to enforce a consistent set of coding style rules (we prefer the AirBnB ruleset)
  • Require.js to load JS modules on demand
  • PPR.js to attach JavaScript to Magnolia components
  • jQuery for PPR’s selectors and AJAX requests
  • Modernizr for browser feature detection

What has been purposefully left out

Frog Rain doesn’t contain any CSS resets, grid frameworks or other visual libraries. We also left out a good bunch of other build scripts we have so as to keep the requirements as low as possible, while still retaining what we think makes Frog Rain great.

How to start a project with Frog Rain

Setting up Frog Rain is quite straightforward. Clone the project from GitHub, run `npm install` and finally `gulp`. This will get you a ready-built light module with a couple of example components ready to be inserted into Magnolia.

Running Magnolia

If you’re going to be developing Magnolia as a full stack developer, you’ll probably want to run Magnolia in your IDE such as Eclipse or IntelliJ IDEA. Consult Magnolia’s excellent Hello Magnolia tutorial on how to achieve this, then adjust Frog Rain’s build scripts to create its output modules into your Magnolia’s module directory. Hint: you could remove the default `magnolia-modules` directory and replace it with a symbolic link to your Magnolia instance’s module directory.

Running a virtual Magnolia using Vagrant

If you don’t want to set up a large and heavy IDE, you can use Vagrant to create and run a local virtual machine hosting Magnolia for you. After installing Vagrant and Oracle VirtualBox, you only need to run the command `vagrant up` and sit back for a while as Vagrant downloads the required Ubuntu images and does all the configuring for you. When it finishes, you should have a local Magnolia instance running at localhost:8888.

Vagrant tries to automatically choose the best method to synchronize the files between your computer and the virtual machine running Magnolia. If the chosen method is the faster rsync, you may need to run the command `vagrant rsync-auto` to start up the synchronization. To use rsync on a Windows machine you need to install it separately. Rsync is included in packages like Cygwin and MinGW.

Creating a new component

Next you’ll probably want to take a look at the example components included with Frog Rain. If you peek inside `src/modules/frog-rain-ui-module/components/example-component` you’ll see the usual Magnolia light module files you’d expect to find inside a light module: the template definition YAML file and a Freemarker template. Additionally, the directory contains an SCSS file and a JS file. These contain all the styles and JavaScript functionality associated with `example-component`.

To create a new component, you can quickly duplicate an existing one, rename the files and change the references in each of the files. This could be automated with a tool similar to magnolia-cli, but since the process needs to be done only once per component we haven’t quite felt the need yet.

Working with multiple light modules

In the quite likely event that you want to call your light module something else than `frog-rain-ui-module`, you can just rename it under your src/modules directory and the changes will be picked up by the build system. All the source files may use the token %MODULE_NAME% which will get replaced by the actual name of the module when it gets built. The same applies for working with multiple modules at once. Just create another directory under `modules` and you’re good to go.

So do you need Frog Rain?

That depends. If you already have a working build system you’re happy with it, it may not be worth the effort to replace it. If you’re new to either Magnolia or front-end development in general, it could give you an easy entry point to get going quickly. You could also install it to see how we do things, take any good parts you find and combine them with your own project to make your awesome build system a bit better.

Frog Rain on Github.

Niko Salminen is a Senior Consultant at Houston


{{item.userId}}   {{item.timestamp | timestampToDate}}

About the author Niko Salminen

Niko Salminen is a Senior Consultant at Houston, a leading digital service development provider based in Helsinki, Finland. He works on software development, web development and database administration and target systems ranging from mobile to enterprise.

See all posts on Niko Salminen