Mojular core

This module is at heart of other Mojular JS packages.

It includes a number of dependencies which are used in a typical project and exposes Mojular global namespace. This core module also includes JSON2 and html5shiv which should be included as polyfills for older IE browsers. jQuery library and lodash utility are also included and can be used in other modules using Webpack module builder.

Installation

Install into your project via NPM:

npm install mojular --save

This has only been tested with Webpack so far, you can install it globally:

npm install webpack -g

Usage

To use in your project create a simple webpack.config.js in your project root:

var webpack = require("webpack");

module.exports = {
  entry: {
    app: 'assets-src/scripts/main.js',
    polyfills: ['JSON2', 'html5shiv']
  },
  output: {
    path: 'assets/scripts',
    filename: '[name].bundle.js'
  },
  module: {
    loaders: [
      { include: /\.json$/, loaders: ['json-loader'] }
    ]
  },
  resolve: {
    modulesDirectories: [
      'node_modules',
      'node_modules/mojular/node_modules'
    ],
    extensions: ['', '.json', '.js']
  },
  plugins: [
    new webpack.optimize.DedupePlugin()
  ]
};

First we create entry points for Webpack. These are our main project’s JS file, all other JS files should be imported via CommmonJS or RequireJS via Webpack’s built-in loaders. JSON2 and html5shiv are a separate entry point as need to be built as separate file.

The output is where Webpack builds bundles. path is the build directory and filename is the name of the file(s). [name] takes the key of each entry property when multiple are specified. The end result is app.bundle.js and polyfills.bundle.js.

Loaders module contains json-loader which allows us to process other packages internal package.json files. This can be used to extract certain meta data about module, such as Sass load paths.

moduleDirectories is extended to look inside Mojular’s dependencies which will give direct access to those mojules from anywhere within project’s source (jQuery, lodash etc). json is also added to extensions so packages.json can be loaded without specifying the extension.

A useful Dedupe Plugin is also loaded to ensure there is no duplicated imports in built outputs, making the resulting output as lean as possible.

To minify JS include UglifyJS plugin:

plugins: [
  new webpack.optimize.UglifyJsPlugin({ minimize: true })
]

To compile the bundles run webpack in the same directory as your Webpack config.

Gulp

Webpack can also be integrated into your project task runner, such as Gulp:

var webpack = require('webpack');
var gutil = require("gulp-util");

gulp.task('scripts', function(callback) {
  webpack(require('./webpack.config.js')).run(function(err, stats) {
    if(err) throw new gutil.PluginError("webpack", err);
    gutil.log("[webpack]", stats.toString({
      colors: true,
      modules: false,
      chunkModules: false
    }));
    callback();
  });
});

Rails

Webpack needs to be run every time JS files are changed. Either run webpack --watch in a separate terminal tab or Use something like Foreman.

web: rails server
webpack: webpack --config webpack.config.js --watch --colors

Then foreman start to run both Rails server and Webpack watch in one place.

In project files

Import files using CommonJS or AMD style.

var Mojular = require('mojular');

Mojular
  // include Mojular JS modules
  .use([
    require('mojular-govuk-elements'),
    require('mojular-moj-elements')
  ])
  .init();

Mojular must be initialised after all other files have been loaded. It will set up basic structure for Mojular app and initialise all modules in Mojular.Modules object.

External modules

A number of external modules exist and expanding. A module would start its life in your project sourceand when it becomes generic enough and useful in other use cases it can be extracted added into one of existing Mojular repos or a new repo can be created.

govuk-elements being the most generic and meant for uses across government sites. moj-elements are modules that currently are used within MoJ organisation. But due to their compatibility (built on top of Heisenberg base) they are interchangeable and can be plugged in to most projects which use Mojular.

Mojular repos may contain supporting styles, images or even templates.