Getting Started

Mantri is installed and managed via NPM, the Node.js package manager.

Mantri is comprised of two packages:

  • mantri The main library that contains the build process and web components.
  • mantri-cli The command line tool to interface with Mantri.

Mantri is also available as a Grunt plugin, if you are not familiar with Grunt you better use the command line tool for convenience.

Installing the CLI

In order to get started, you'll want to install Mantri's command line interface (CLI) globally. You may need to use sudo (for OSX, *nix, BSD etc) or run your command shell as Administrator (for Windows) to do this.

npm install -g mantri-cli

This will put the mantri command in your system path, allowing it to be run from any directory.

Note that installing mantri-cli does not install the mantri library! The job of the Mantri CLI is simple: run the version of Mantri which has been installed in your project. This allows multiple versions of Mantri to be installed on the same machine simultaneously.

Creating the First Project

From your project's root folder, install the Mantri library.

npm install mantri --save-dev

During development, your web application needs two files to operate, the web runtime and Mantri configuration. The Mantri runtime is the only javascript file you need to include in your html document. To get those two files run the init cli command.

mantri init

This will create the files mantri.web.js and mantriConf.json in your current directory. Use the -h flag to get help for the Mantri CLI in general or a spefic command mantri init -h.

Your Web Application

Dependency Declarations

Mantri expects that you make goog.provide() and optionally goog.require() declarations at the top of all your files.

/**
 * @fileoverview The user model.
 */
goog.provide('myApp.model.user');

goog.require('myApp.Events');
goog.require('myApp.helpers');

You can declare all your third-party dependencies in the mantriConf.json configuration file. Once defined, Mantri will load them before your application and they will be available in the global context, e.g. access jQuery like you would using the global $ or jQuery variables.

Your HTML Document

The html document should look something like this:

{{#if development}}
  <script data-require="app" src="js/vendor/mantri.web.js"></script>
{{else}}
  <script src="//xxx.cloudfront.net/42/buildApp.js"></script>
{{/if}}

Resolving Dependencies

As you've noticed, you are providing and requiring namespaces, not filenames. This enables some interesting feats like being able to move files around without the need to update any of your files. Mantri will do the dirty job for you by scanning and mapping the namespaces to actual filenames, this is called the deps command.

mantri deps --src=js/ --dest=js/deps.js

If you create or edit a dependency declaration you will need to run the deps command.

The mantriConf.json File

The mantriConf.json file is the main configuration file for Mantri. By default, Mantri looks for this file in your Document Root, except declared otherwise.

The type of the file is JSON, therefore no comments or funny stuff, think package.json.

This is a sample mantriConf file:

{
  "jsRoot": "js/",
  "vendorLibs": {
    "jquery": "../assets/jquery.min",
    "handlebars": "../assets/handlebars.min",
    "ember": "lib/ember-latest.min"
  },

  "deps": {
    "src": "js/",
    "root": "./",
    "dest": "deps.js"
  },

  "build": {
    "src": "js/app.js",
    "dest": "dist/app.min.js",
    "outputWrapper": "(function(){%output%}).call(this);",
    "excludeVendor": ["jquery"]
  }
}

The build.src option must point to the file that bootstraps your application.

Production

Building your application is one command line away:

mantri build

This is roughly what happens when build is run:

  • Reads your mantriConf.json file and parses the build rules.
  • Scans your codebase and creates a dependency tree.
  • Bundles all the vendor libraries in the order you declared them.
  • Bundles your application in one file based on the dependency tree.
  • Removes all goog.provide() and goog.require() declarations.
  • Compiles the whole bundle with the powerful Closure Compiler.
  • Optionally wraps your code in anything you like (AMD, CommonJS, anon function, you name it).

Examples

Clone the classical ToDo MVC Application using the Mantri Dependency System:

git clone git@github.com:closureplease/todoAppMantri.git

Launch a static web-server, or type grunt deps and grunt build to see Mantri in action.