Modules

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.

Collaborative

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.

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.

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.

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.

Copy Compilers

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.

Copy/Transpile

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

Testing

Asset Optimization & Concatenation

Packaging and Installation

Static Analysis

Require JS Related

Ember.js Specific

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

On the Server

The Rest

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.

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

template: {
  output: [{
    folders:["search","shared"],
    outputFileName: "search_templates"
  },{
    folders:["user","shared"],
    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.

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

List Available/Installed Modules

mod:list

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)

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

Get more details (-v/--verbose)

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

Install a Module

mod:install

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

mod:uninstall

$ mimosa mod:uninstall mimosa-server