See the Modules page for more information on Mimosa's workflows. The following is an example of the processing Mimosa invokes to compile a file.

1) watch

Mimosa watches the directory configured with the watch.sourceDir property in the mimosa-config, which is by default the assets directory. Whenever a file is added, updated or deleted in that directory, Mimosa's workflows are kicked off.

2) compile

Mimosa will match an asset to a compiler for that asset using a set of default extensions. The table at the top of this page details all of the compiler default extensions. So, for example, if a .coffee file is changed, Mimosa will compile that as CoffeeScript. To use a non-default extension, use the compilers.extensionOverrides property of the mimosa-config to map the extension to a compiler. If Mimosa cannot find a compiler for a file, Mimosa logs that to the console.

If a compiler is found and compilation fails, Mimosa will notify via Growl (if it is installed) and the console. When compilation fails, Mimosa will stop processing the file.

3) lint

To 'lint' code is to check it for common mistakes or variances from the idiom. Both successfully compiled CSS and JavaScript will pass through a linting step and output lint errors as warnings to the console. mLint errors will not halt the workflow, but they'll be there when you want to go clean things up.

4) output

For all Mimosa commands except virgin, Mimosa will output compiled code to the watch.compiledDir. virgin does not write the output.

5) notify

During the processing of a file, if something goes wrong, Mimosa will provide feedback. And if everything is successful, Mimosa will output that too. Notifications are configurable, so certain notifications can be turned on or off.

Mimosa allows using every single one of its compilers in a single project if that's how you roll. If a saved file has an extension that Mimosa recognizes, Mimosa will compile it. One use case for this is to use Twitter Bootstrap's source LESS alongside a project's Stylus. Mimosa will happily compile Bootstrap with any custom modifications. And it'll compile Stylus files too.

Mimosa currently supports the following JavaScript Meta-Languages. Next to the name of each is the Mimosa name and the list of default extensions Mimosa recognizes.

CoffeeScript coffee ["coffee", "litcoffee"]

CoffeeScript is one of Mimosa's compilers, and is a Mimosa favorite as Mimosa itself is coded using CoffeeScript. Mimosa will treat files ending in .coffee as CoffeeScript files.

By default, during mimosa watch Mimosa will also generate source maps. Source maps map lines of compiled JavaScript back to lines of the original CoffeeScript source. So when something breaks in the compiled JavaScript, tools like the Chrome Dev Tools will show you the responsible line of CoffeeScript. The inclusion of source maps eliminates one of the chief concerns with using this particular compiles-to-JavaScript language. Source maps are turned off by default for mimosa build.

CoffeeScript, by default, wraps compiled JavaScript in a safety wrapper to protect scope. Mimosa turns this wrapping off by compiling bare by default. Mimosa does this because it assumes code is already being wrapped in AMD or CommonJS/AMD functions define or require.

Mimosa provides the full ability to configure the CoffeeScript compiler via the mimosa-config. Source maps can be turned off, bare compilation can be turned off, and any other flags/settings CoffeeScript exposes to tweak compilation can be added. The following is the default config for the CoffeeScript compiler.

coffeescript:
  sourceMap:true
  sourceMapExclude: [[/\/spec\//]]
  bare:true

The sourceMapExclude property is not a CoffeeScript compiler instruction, but one for Mimosa. Any files paths that match the entries in thesourceMapExclude will not have source maps generated.

Mimosa will also compile Literate CoffeeScript files if they end with the extension litcoffee.

Iced CoffeeScript iced ['iced']

Iced CoffeeScript is available as an option for folks who want some async sugar in their Coffee.

Like CoffeeScript, Iced CoffeeScript, by default, wraps compiled JavaScript in a safety wrapper to protect scope. Mimosa turns this wrapping off by compiling bare by default. Mimosa does this because it assumes code is already being wrapped in AMD or CommonJS/AMD functions define or require.

Mimosa provides the full ability to configure the Iced CoffeeScript compiler via the mimosa-config. bare compilation can be turned off, and any other flags/settings Iced CoffeeScript exposes to tweak compilation can be added. The following is the default config for the Iced CoffeeScript compiler.

iced:
  bare:true

LiveScript livescript ['ls']

LiveScript is available as an option for those that enjoy some functional hotness and squiggly arrows.

TypeScript typescript ['ts']

Like the idea of typed JavaScript? TypeScript might be for you.

TypeScript has a small bit of its own configuration that isn't documented elsewhere.

typescript:
  module:null

The module config is used to set how TypeScript will wrap compiled TypeScript. The default is null, which will not wrap the compiled code. Other options are amd and commonjs which will wrap compiled code as expected for each.

TypeScript support was new with version 0.7.0 of Mimosa, and it is experimental. Feedback from TypeScripters would be huge. What flags and features should be available? Also, the code provided by mimosa new is not even close to being idiomatic TypeScript. Lend a hand in fixing it?

This isn't an Earth-shattering feature, and for most of the compilers, compilation time is so fast it doesn't matter. Users of SASS via JRuby will be greatly appreciative though, that Mimosa is selective about which files to compile.

The list of CSS compilers follows. Next to each name is the Mimosa name and the list of default extensions.

Stylus w/nib stylus ["styl"]

Stylus with nib is available. Mimosa will look for files ending in .styl and treat them as Stylus files. Stylus is a node library (as is nib), so there is no need to install anything to use it, and Stylus compiles will be speedy.

Stylus has its own configuration:

stylus:
  use:['nib']

This configuration allows for the addition of external Stylus libraries to the compilation of a project's Stylus without needing to include the external libraries' source code in the project. For each entry in the array, Mimosa will expect that it can find the library installed within the project. So, for instance, to use this config use:['stylusFoo'], then at some point "stylusFoo" would have had to have been executed via npm install stylusFoo. The exception to this rule is "nib", which comes installed within Mimosa and does not need to be installed in the project.

SASS w/Compass sass ["scss", "sass"]

SASS w/Compass is another Mimosa option. SASS (install) and Compass (install) are Ruby gems and there isn't yet a full implementation of them in nodejs, so Mimosa is dependent on those gems being installed. Compass isn't a necessary install, but Mimosa will complain if SASS is used but not installed.

LESS less ["less"]

Mimosa will also compile LESS. LESS is a node library, so there is no need to install anything to use it, and LESS compiles will be speedy.

Listed below are the different micro-templating libraries built into Mimosa. For performance reasons, templates should be pre-compiled on the server rather than the browser. Mimosa pre-compiles templates. As with the CSS and JavaScript meta-languages, micro-templates will be compiled when saved. 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. Despite what directory a template is in, 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. Mimosa will handle including that library in your project. It will place an AMD wrapped version of the library inside the watch.javascriptDir/vendor 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 a requirejs path alias is set up pointing at the library, like underscore:"vendor/underscore", Mimosa will use the path. The following are the names of the libraries Mimosa places in watch.javascriptDir/vendor directory.

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, see below.

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.

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 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 follows:

template:
  output: [{
    folders:["search","shared"]
    outputFileName: "search_templates"
  },
  {
    folders:["user","shared"]
    outputFileName: "user_templates"
  }]

Multiple Template Libraries

As with the CSS and JavaScript compilers, 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. The mimosa-config includes a commented out example.

Not AMD wrapped

For all the options above, Mimosa wraps the compiled templates in an AMD define block. If a project is not using AMD, this would cause problems. At the root of the template config is an amdWrap flag. By default amdWrap is set to true. When set to false Mimosa will not wrap the template output. 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.

Next to the name of each micro-templater below is the Mimosa name and the list of default extensions Mimosa recognizes.

Handlebars handlebars ["hbs", "handlebars"]

Handlebars is available. To access a Handlebars template originating from a file named "example.hbs"...

var html = templates.example({})

...passing in JSON data the template needs to render.

Handlebars also provides the ability to include reusable helper methods. Those can be coded in any meta-language and should be included inside the compilers.template.handlebars.helpers array.

Because all of the templates are compiled together, helpers, {{example-helper}}, are immediately available without any extra work. Also, partials do not require Handlebars.registerPartial to be called. The output template.js file is modified to access the entire list of templates when attempting to insert a partial.

Mimosa keeps an AMD wrapped version of Handlebars that it writes to assets/javascripts/vendor/handlebars.js directory as part of compilation, so there is no need to include the library.

Got Ember?

Ember.js uses Handlebars, but its a Handlebars that is Ember specific. Mimosa's includes Ember Handlebars pre-compilation out of the box with minimal config. By default, vanilla Handlebars will compile all of the .hbs and .handlebars files it comes across. To enable Ember Handlebars pre-compilation, use the template.handlebars config.

template:
  handlebars:
    ember:
      enabled:true
      path:"vendor/ember"

ember.enabled selects the Ember Handlebars pre-compiler as the compiler that will handle Handlebars templates. path is the AMD location of the Ember library, which defaults to vendor/ember.

When Ember Handlebars is enabled, Mimosa will not write the AMD version of Handlebars to the public directory as it does with all the other compilers including vanilla Handlebars.

Emblem emblem ["emblem", "embl"]

Emblem is available. To access a Emblem template originating from a file named "example.embl"...

var html = templates.example({})

Emblem precompiles to the same functions that Handlebars does and from there on using Emblem is the same as using Handlebars. All of the Handlebars documentation above applies, including...

Got Ember?

Emblem utilizes the same ember config that Handlebars does, so when handlebars.ember.enabled is set to true, Mimosa will output Ember-compliant Handlebars functions. See the Handlebars documentation above for more details.

Dust dust ["dust"]

To access a Dust template originating from a file named "example.dust"...

templates.render('example', {}, (err, html) -> $(element).append(html))

Dust partials can be referenced, {>example_partial/}, and they will be available because all the templates are merged together.

Mimosa keeps an AMD wrapped version of Dust that it writes to assets/javascripts/vendor/dust.js directory as part of compilation, so there is no need to include the library.

Hogan hogan ["hog", "hogan", "hjs"]

To access a Hogan template originating from a file named "example.hogan"...

templates.example.render({}, templates)

Note the passing of the templates object into the render method. This isn't necessary, but if partials are used, it needed to make partials work since all partials are included in the compiled template file. Hogan's partials are available as normal, {{>example-partial}}.

Mimosa keeps an AMD wrapped version of Hogan that it writes to assets/javascripts/vendor/hogan-template.js directory as part of compilation, so there is no need to include the library.

Jade jade ["jade"]

To access a Jade template originating from a file named "example.jade"...

var html = templates.example({})

Including a partial is easy: include example-partial.

Mimosa keeps an AMD wrapped version of Jade that it writes to assets/javascripts/vendor/jade-runtime.js directory as part of compilation, so there is no need to include the library.

Underscore underscore ["tpl", "underscore"]

To access an Underscore template originating from a file named "example.tpl"...

var html = templates.example({})

Mimosa keeps an AMD wrapped version of Underscore that it writes to assets/javascripts/vendor/underscore.js directory as part of compilation, so there is no need to include the library yourself if you are just using it for templating.

Lodash lodash ["tmpl", "lodash"]

To access a LoDash template originating from a file named "example.lodash", do this...

var html = templates.example({})

Mimosa keeps an AMD wrapped version of Lodash that it writes to assets/javascripts/vendor/lodash.js directory as part of compilation, so there is no need to include the library.

Embedded JavaScript Templates (EJS) ejs ["ejs"]

To access an EJS template originating from a file named "example.ejs"...

var html = templates.example({}, filters, escape)

Mimosa keeps an AMD wrapped version of EJS' filters that it writes to assets/javascripts/vendor/ejs-filters.js directory as part of compilation. Mimosa's compiled EJS file will use those filters, but this can be overridden with custom filters.

HTML html ["template"]

Plain HTML templates can be used too.

To access a plain HTML template originating from a file named "example.template", do this...

var html = templates.example

Full disclosure: Mimosa uses Underscore under the hood to handle getting plain HTML templates to the browser as strings. In this case, the Underscore compiler has been made so that it'll not understand it's usual delimiters for code or interpolation, and the resulting compiled Underscore templates are delivered as self-executing.

Mimosa maintains a list of extensions that it will simply copy from the assets directory to the public directory. Because of the copy compiler, images, plain JavaScript, CSS will not be left out.

If there are extra files to copy over, uncomment the copy.extensions config and add it to the list. If the default list of extensions for the copy compiler needs to be updated, consider submitting an issue to have new extensions added to Mimosa's defaults.