The Configuration File

mantriConf.json is the main Mantri configuration file. From this file you control every functionality and option of the Mantri building workflow.

Not For Production!

The mantriConf.json file should not exist in your production environment. Make sure you remove it at deployment. To define another location for the file use the data-config attribute in the <script> element:

<script data-config="js/config/mantriConf.json" src="js/libs/mantri.web.js"></script>

General Options

jsRoot

Type: string Default: Directory of mantriConf.json file.

The base folder of your Javascript application, relative to your Document Root.

Absolute Paths

For cases where you need absolute paths feel free to use /. Using ./ means literally the current path. Helps if your application lives under a folder.

Deprecation Notice: This used to be the baseUrl option key. Since v0.2.0 it has been deprecated and in v0.3.0 the baseUrl key will be permanently removed.

documentRoot

Type: string Default: Directory of mantriConf.json file.

Defines the base folder of your website. If the mantriConf.json file is not in your website's root folder, then you have to define this option!

closureLibrary

Type: string Default: None.

In case you want to include modules from the Closure Library then you need to define the path using this key.

vendorLibs

Type: Object Default: None

Define all your third-party dependencies in this object. the key of the object is the lib's id and the value is the path to the file.

Example:

{
  vendorLibs: {
    "jquery": "vendor/jquery.min",
    "handlebars": "vendor/handlebars.min",
    "ember": "vendor/ember-latest.min"
  }
}

The path will get concatenated with the path from jsRoot, so from the example above, if jsRoot was set to js jquery would be looked up in js/vendor/jquery.min.js. Feel free to use ../ if you need to escape that.

Insight: The key used to id the lib can be used by the build.excludeVendor option to exclude a lib from the final built bundle.

Deprecation Notice: This used to be the lib option key. Since v0.2.0 it has been deprecated and in v0.3.0 the lib key will be permanently removed.

The Dependency Task Options

The dependency task calculates your dependency tree and produces the deps.js file which is required in development by Mantri. All dependency options are nested under the deps master key.

deps.src

Type: string Default: ./

The source to scan for goog.provide and goog.require statements, essentialy the path to your web application.

The source must be a string representing an actual folder. It cannot be an array or use globbing patterns.

Be careful when defining a source. If the source is different from your document (web) root, you will need to define the documentroot using the root option.

deps.root

Type: string Default: ./

The root option defines the Document (web) Root directory of your website. It is required if you define the source option.

deps.dest

Type: string Default: deps.js

The file you wish the generated deps file to be saved at.

The Build Task Options

All build option paths should be relative to where your package root folder is (i.e. where your package.json file is).

build.src

Type: string Default: Required

Define the location of the application bootstrap file. The filename should include the .js extension.

Deprecation Notice: This used to be the build.input option key. Since v0.2.0 it has been deprecated and in v0.3.0 the build.input key will be permanently removed.

build.dest

Type: string Default: app.min.js

Define the destination output file.

build.outputWrapper

Type: string Default: None

Define a wrapping string for your build application. Use the keyword %output% to position the content of your app:

"build": {
  "outputWrapper": "(function(){%output%}).call(this);"
}

This will wrap your application in an IIFE, which will be self invoked using the Global context.

The string passed to the outputWrapper option will be evaluated using Google Closure's native output-wrapper format.

build.excludeVendor

Type: Array of strings Default: None

Define the libraries that you want to exclude from bundling. This is useful when you want to load popular libraries from public CDN hosts.

Use the key part of the vendorLibs map to refer to vendor libs you want excluded.

Deprecation Notice: This used to be the build.exclude option key. Since v0.2.0 it has been deprecated and in v0.3.0 the build.exclude key will be permanently removed.

build.sourceMapFile

Type: string Default: None

Set the location to store the sourcemap of the build output. Read more about working with Source Maps on Mantri.

build.sourceMapUrl

Type: string Default: None

Set where the browser should expect to find the sourceMap file. Read more about working with Source Maps on Mantri.

Building Multiple Modules

buildModules

Type: Object Default: None

Mantri allows building multiple modules in case you need to lazy load your JS assets. The key to set this up is buildModules and it's a map of configs for each module to build:

buildModules: {
    "app.moduleA": {
      "dest": "dist/app-module-A.min.js",
      "sourceMapFile": "dist/app-module-A.min.js.map",
      "sourceMappingURL": "/dist/app-module-A.min.js.map"
    },
    "app.moduleB": {
      "dest": "dist/app-module-B.min.js",
      "sourceMapFile": "dist/app-module-B.min.js.map",
      "sourceMappingURL": "/dist/app-module-B.min.js.map"
    }
}

The key in an actual reference to the Module's namespace. Each module Object can have the following keys:

  • dest Type: string Default: Required :: Where to save the compiled output.
  • sourceMapFile Type: string Default: None :: Optionally set where to save the sourcemap file.
  • sourceMapURL Type: string Default: None :: Optionally set where your browser should look for the sourceMap file.
  • outputWrapper Type: string Default: None :: Do not use this unless you know what you are doing, needs to properly export symbols.

Multiple builds is a very advanced topic, read more about how to implement it.

mantriConf.json Examples

A typical configuration file:

{
  "baseUrl": "js/",
  "vendorLibs": {
    "jquery": "vendor/jquery.latest",
    "handlebars": "vendor/handlebars.min"
  },

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

  "build": {
    "src": "js/app.js",
    "dest": "dist/app.min.js",
    "outputWrapper": "(function(){var BUILD=true;%output}).call(this)",
    "excludeVendor": [
      "jquery"
    ],
    "sourceMapFile": "dist/app.min.js.map",
    "sourceMappingURL": "/dist/app.min.js.map"
  }
}