Extend Mimosa's default functionality

What is a Module?

A Mimosa module is a node.js package that, when installed inside Mimosa or your project, can be used as part of Mimosa's workflows. Mimosa is able to use a module because modules implement a simple interface Mimosa understands and can use.

Process Files in Memory

Unlike other build tools, Mimosa modules do not rely on communicating with each other via the file system. Mimosa's core is responsible for lining up the modules on an execution conveyor belt, passing information from one module to another directly. So, for example, a CoffeeScript file can be read, compiled, linted, minified, written to disk and live reload-ed in the browser -- effectively being touched by 6 modules -- with only two IOs: the read of the input CoffeeScript and the write of the output minified JavaScript. This keeps Mimosa fast. Live Reload will kick off before you even get a chance to toggle back to the browser.


Modules are collaborative in nature. They can access other modules directly. One good example is the dependency-graph module which creates d3 visualizations depicting an application's dependency tree. Rather than needing to build the dependency tree itself, that module can utilize the data already available in the mimosa-require module, which exposes a dependency object. This lets the module author just focus on using d3 to create a cool visualization.

Module List

The tables below contain an abbreviated list of available Mimosa modules. If you are interested to see if a specific module is available, the best place to search, besides Google, is NPM, where all the modules are registered.

JavaScript Compilers

Mimosa core's JavaScript compiler wraps the following module compilers and provides a base level of common functionality.

babelA babel (formerly 6to5) compiler
coffeescriptA CoffeeScript compiler
iced-coffeescriptAn Iced Coffeescript compiler
emberscriptAn EmberScript compiler.
cocoA Coco compiler.
livescriptA LiveScript compiler.
reactA React compiler.
cjsxA CoffeeScript + JSX/React compiler.
typescriptA TypeScript compiler./td>

CSS Compilers

Mimosa does a little bit of extra work with CSS. Mimosa takes care not to compile files that do not need it. If CSS gets included back through a single base CSS file, changing a file deep down the tree of includes will only trigger a compile of that single base file and not the changed file. Similarly if there are multiple base files, changing a file included in two places will trigger the recompile of those two files.

stylusA Stylus CSS pre-processor with built-in nib support.
sassA SASS CSS pre-processor that works with both node-sass and Ruby SASS.
lessA Less CSS pre-processor.

Micro-Templating Compilers

Using the following compiler modules Mimosa will precompile your project's templates. Based on its configuration, Mimosa will create one-to-many compiled template files. See the template documentation below and the general configuration for templates for details on base template compiler behavior.

handlebarsA Handlebars template compiler.
ember-handlebarsA Handlebars template compiler specific for use with Ember.js
ember-htmlbarsA HTMLBars template compiler specific for use with Ember.js
emblemAn Emblem template compiler.
dustA Dust template compiler.
hoganA Hogan template compiler
jadeA Jade template compiler.
jade-staticA Jade template compiler that outputs HTML rather than dynamic templates.
underscoreAn Underscore template compiler
lodashA Lodash template compiler.
ejsAn EJS template compiler.
ecoAn ECO template compiler.
ractiveA Ractive template compiler.
nunjucksA Nunjucks template compiler.
twigA Twig template compiler.
html-templatesPlain, non-dynamic, HTML templates

Copy Compilers

copyA file copying module responsible for transporting files from Mimosa's input directory to its output directory. By default it copies 25+ different types of files.

Miscellaneous Compilers

Miscellaneous compilers don't fit nicely into the categories above. They don't copy files, transpile JavaScript, pre-process CSS or compile templates.

There are currently no Miscellaneous compilers, if you are interested in creating one, check out this example Miscellaeous compiler.


The following are additional modules that compile/copy/transpile assets but are not considered "compilers" by Mimosa.

ember-module-importBuilds ember.js module manifests for an AMD/CommonJS-based application
stream-copyCopies files that do not need to be processed otherwise by Mimosa and it does so with super-fast streams.
markdownCompiles markdown syntax to html.
mythA simple Myth CSS preprocessor module.
regeneratorUse ES6 generator syntax today. This module compiles ES6 generators down to ES5 compatible javascript.
esperanto-es6-modulesUse ES6 module syntax today. This module compiles ES6 module syntax down to AMD or CommonJS.
es6-module-transpilerUse ES6 module syntax today. This module compiles ES6 module syntax down to AMD, CommonJS or globals.
client-jade-staticCompiles Jade files with a ".html.jade" extension statically and writes them out as individual plain HTML files.
jade-staticActually a template compiler like any other that executes compiled jade templates, transforming them to HTML and then merging the templates into a single file.
hogan-staticCompiles individual Hogan/Mustache templates to separate html files while allowing for partials and template contexts to be provided.


phantomcssRun automated visual testing via PhantomCSS.
ember-testEmber specific QUnit/Testem test integration.
testem-qunitA Testem, QUnit, Sinon, Chai integration that utilizes your RequireJS config and spec naming conventions to allow for immediate testing, no configuration required.
testem-requireA Testem, Mocha, Sinon, Chai integration that utilizes your RequireJS config and spec naming conventions to allow for immediate testing, no configuration required.
testem-simpleSimple Testem test runner integration.
karmaKarma test runner integration.
karma-enterpriseAdvanced and maintained Karma test runner integration.
jasmine-nodeStart up a Jasmine-Node test suite alongside Mimosa

Asset Optimization & Concatenation

vulcanizeWeb component optimization support via Polymer/Vulcanize
requireAMD/RequireJS support including optimization
uncssRemoves unused CSS as part of a build.
minify-cssMinification of CSS assets
minify-jsMinification of JS assets
minify-htmlHTML minification.
htmlcleanHTML cleaning.
minify-svgSVG minification.
minify-imgImage minification.
minify-jsonJSON minification.
spriteGenerate CSS sprite images and stylesheets.
spritesmithGenerate CSS sprite images and stylesheets. With retina support.
combineCombine all non-binary files in a folder into a single file

Packaging and Installation

build-taskRun scripts/servers during a mimosa build.
npm-web-dependenciesInstall web dependencies from NPM using Browserify.
bowerBower integration for managing vendor assets.
defeatureWill slice individual features out of an application's templates, javascript and CSS at build time.
fix-rjs-emberThis module addresses specific issues with Ember.js packaging via r.js. The issues were introduced with version 1.7 of Ember but fixed with version 1.8+.
groundskeeperClean console.log, debugger and pragmas from your code during a build.
dependency-bundlerBundles multiple AMD modules into a single module for easy import.
asset-cache-bustAsset cache busting.
browserifyA module for the very popular CommonJS node-in-the-browser build tool.
require-library-packagePackage up library code built using AMD/RequireJS for use in other applications.
web-packagePackaging of a web application for deployment.
rpm-packagePackaging of a web application for deployment as an RPM.
s3-deployerDeploy your static files to AWS S3.

Static Analysis

csslintRun CSSLint over your CSS.
jshintRun JSHint over your JavaScript code.
jscsWraps the popular JSCS JavaScript style checking utility.
css-colorguardTells you if you have colors in your CSS that are too close together.
eslintRuns ESLint over your JavaScript code.
platoRun the Plato Static Analysis tool over your JavaScript.
require-lintDetect unused dependencies in your AMD code.
dependency-graphBuild awesome d3 visualizations of your require.js dependency graph.
coffeelintProcess your CoffeeScript for style and variances from the language idiom.
js-validateParses JavaScript to ensure code is valid.

Require JS Related

requireAMD/RequireJS support including optimization
require-commonjsCommonJS support via AMD/RequireJS
requirebuild-includeA module to include assets into r.js runs before optimization occurs.
requirebuild-textplugin-includeWill include files attached to the text plugin to r.js runs.
requirebuild-module-includeFind dependencies and include them in r.js module config include arrays.
requirebuild-textplugin-module-includeFind text dependencies and include them in r.js module config include arrays.

Ember.js Specific

Building an Ember app? Mimosa isn't Ember specific, but these modules are.

ember-module-importBuilds ember.js module manifests for an AMD/CommonJS-based application
fix-rjs-ember(For Ember pre-1.8) This module addresses specific issues with Ember.js packaging via r.js. The issues were introduced with version 1.7 of ember.
ember-envAdds EmberENV object to ember library.
ember-handlebarsEmber specific Handlebars template compilation.
ember-htmlbarsEmber specific HTMLBars template compilation.
ember-testEmber specific QUnit/Testem test integration.

On the Server

serverMimosa-based hosting and managing of node-based user hosting
live-reloadApplication reloads when the code does
start-serverStart your server when the build completes.
server-template-compileCopy your server templates into static HTML as part of a build.
server-reloadRestart a node server when server assets change.

The Rest

coffeescript-preprocessBefore coffeescript is compiled replace template-like variables in the code.
replacePerform simple text replacement.
renameRename files before they are written to output.
svgs-to-iconfontsGenerate a full set of icon fonts from a set of svg files.
restartAutomatically restarts a running Mimosa when the compiled directory is deleted.
vaultUses the vault project to generate passwords derived from a secret key.
autoprefixerThis module will automatically prefix your vendor CSS and provides source map support.
handlebars-on-windowUse this module to alter handlebars.js to place Handlebars on the window object.
d3-on-windowUse this module to alter d3.js to place d3 on the window object.
post-hookRun scripts/commands at the end of the mimosa watch startup.
just-copyAllow assets to bypass Mimosa module processing and just be copied.
import-sourceCopy other files into a project to be included as part of the project.
voloIntroduces a import command that wraps Volo functionality. Comprises the import command that came bundled with Mimosa pre 0.7.2.

Installing and Using Modules

There are several ways to install a module.

Easiest Way: add the module name to the mimosa-config modules array

One way to install a module is to just add the name to the modules array in the mimosa-config. This is a shortcut for the project level npm install (covered next). The next time Mimosa is started for that project it will install the module into the Mimosa project from NPM.

To use a module it needs to be added to the modules array anyway, so this shortcut saves the installation step.

npm install

Install Mimosa modules in the project itself and Mimosa will prioritize those modules above all others. Run npm install mimosa-nameOfModule and the module will be installed. Modules installed inside a project take precedence over any modules installed into other scopes.

mimosa mod:install

One way to install a module is the mod:install command discussed further below. mimosa mod:install mimosa-web-package will install mimosa-web-package from NPM. The module will still need to be added to any projects that need to use it. This command adds the module to the globally installed Mimosa making it available to every Mimosa project.

npm install -g

Use npm install -g to install any modules into the global node scope. Modules installed with mod:install take priority, so if any modules are installed with both npm install -g and mod:install, the npm install -g module will be ignored.

Install specific module version

To install a specific version of a module, to, for instance, ensure everyone on a project stays on the same version, add a @ followed by the version after the module name. Ex: web-package@0.1.0. This can also be accomplished by managing versions in a project's package.json.

Using Template Compilers

For performance reasons, templates should be pre-compiled on the server rather than the browser. Mimosa, through many external compiler modules (see the list at the top of the page) will precompile a project's templates. Based on its configuration, Mimosa will create one-to-many compiled template files. See Output Variations below for the output options.

For each templating language, the compiled template files provide a JavaScript object of templates, keyed by the template file name (the default configuration for template name). Each template needs to have a unique name. Should this be violated, Mimosa will warn of template collision issues.

Most of the libraries require a client side version to run the compiled templates. If using AMD wrapping for your templates (more on that below), most Mimosa template compilers will handle including that library in your project. They will place an AMD wrapped version of the library inside the vendor.javascripts library and reference it from the compiled template file. If a library that matches Mimosa's name for the library exists, Mimosa will not overwrite that file. Also, if using AMD wrapping and a requirejs path alias is set up pointing at the library, like underscore:"vendor/underscore", Mimosa will use the path.

Output Variations

Single Template Output

By default the resulting compiled templates will be merged into a single AMD-wrapped file for use in the client. The name and location of that single file is configurable, compilers.template.outputFileName, but by default it is kept at javascripts/templates.js. Use of the templates in this file differs per library, so see the template compiler documentation for details.

Multiple Template Output

If a single-page web app is being built, then a single template file is ideal and Mimosa's defaults can be left alone. But if a site has multiple pages, then ideally Mimosa should build a template file per page.

template: {
  output: [{
    outputFileName: "search_templates"
    outputFileName: "user_templates"

The mimosa-config can be altered to build multiple compiled template output files. Instead of using template.outputFileName, use the template.output array. Each element in the array has a folders array and an outputFileName. output[].outputFileName is identical to template.outputFileName except that is has no default so it must be provided. folders specifies which folders of templates should be bundled together. Every template contained in the folder structure under each of the folders will be compiled and concatenated into the output file. The mimosa-config-documented also includes a commented out example for this configuration.

So, for example, if an app has two pages, "search" and "user", which each have many templates of their own (inside "search" and "user" directories), but that also share common templates from a "shared" folder, that can be configured as listed here.

Multiple Template Libraries

Multiple templating libraries can be used at once, but to do so properly, there is some additional config Mimosa needs. Mimosa bundles templates into the same file, but templates from different libraries don't belong in the same file. So if multiple libraries are being used, provide Mimosa, via the mimosa-config, a map/hash of compiler name to output file name with the template.outputFileName (or the template.output[].outputFileName) config property.

Not Wrapped at All

If template.wrapType is set to none, then Mimosa does no wrapping. Mimosa will also not write the AMD-wrapped template client library into the watch.javascriptDir/vendor directory. If going the non-AMD route, the client library must be provided by the project.

CommonJS Compliant

If template.wrapType config is set to common, Mimosa will create CommonJS compliant template files. Mimosa will also not write any client libraries so the project author must provide a version of the library that works in a CommonJS project.

Module Commands

Each command has a section dedicated to it below, but here is a quick list of the available module commands.

List all Mimosa modules in NPM, or, with a flag, just those you have installed including version information.
mod:install<moduleName>Install a Mimosa module into your global Mimosa.
mod:uninstall<moduleName>Remove a Mimosa module from your global Mimosa.

List Available/Installed Modules


mod:list will search NPM to find all available Mimosa modules. mod:list will list the most recent version of the module and if that module is currently installed, the installed version. If there is a difference, the installed version will be colored to signal that the version is out of date.

Just the installed modules (-i/--installed)

Execute mod:list with the --installed flag to limit the full list to just those currently installed.

$ mimosa mod:list -installed
$ mimosa mod:list -i

Get more details (-v/--verbose)

Add a --verbose flag and Mimosa will including a short description and the list of dependencies the module has on other node.js modules.

$ mimosa mod:list --verbose
$ mimosa mod:list -v

Install a Module


To install a module execute mimosa mod:install and provide the name of the module.

$ mimosa mod:install mimosa-server

If the module has already been installed, this will update it to the latest version. To install a specific version of a module, add the version after a @.

$ mimosa mod:install mimosa-server@0.2.0

To use and test a module under local development that isn't in NPM execute mod:install without providing a name for the module. For this to work properly, the command must be executed from the same directory as the module's package.json, which should be the root of the module. Once the module is installed, Mimosa treats it the same as a module it installed from NPM.

Uninstall a Module


Execute mod:uninstall to remove a module from the Mimosa global install. This will not remove it from your local project if it is installed there. To do that simply remove it from the node_modules directory.

$ mimosa mod:uninstall mimosa-server