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.
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.
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.
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.
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.
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.
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.
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.
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.
Niko Salminen is a Senior Consultant at Houston.
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