Compilers

JavaScript, CSS, Micro-Templating. You write it, Mimosa will compile it.

The following list of Mimosa modules that meet the compiler spec for their compiler type. To use one of these, simple add the "Mimosa Name" to your modules array. Each of the compilers has its own configuration which can be found on its GitHub page.

JavaScript

Name Mimosa Name Default Mimosa Extensions
CoffeeScript coffee coffee, litcoffee
Iced CoffeeScript iced-coffeescript iced
EmberScript emberscript em
Coco coco coco, co
LiveScript livescript ls
JSX/React react jsx
CoffeeScript/JSX/React cjsx cjsx
TypeScript - TypeScript support is experimental, provide feedback typescript ts

CSS

Name Mimosa Name Default Mimosa Extensions
Stylus w/nib stylus styl
SASS w/Compass sass scss, sass
LESS less less

Micro-Templating

Name Mimosa Name Default Mimosa Extensions
Handlebars handlebars hbs, handlebars
Ember Handlebars ember-handlebars hbs, handlebars
Emblem emblem emblem, embl
Dust dust dust
Hogan hogan hog, hogan, hjs
Jade jade jade
JadeStatic jadeStatic jade
Underscore underscore tpl, underscore
Lodash lodash tmpl, lodash
EJS ejs ejs
ECO eco eco
Ractive ractive rtv, rac
Nunjucks nunjucks njs
Plain HTML html-templates template

Copy

The file copying module manages files that do not need compiling, like images or plain .js or .css files.

Name Mimosa Name Copied Extensions
File copying module copy js, css, png, jpg, jpeg, gif, html, eot, svg, ttf, woff, otf, yaml, kml, ico, htc, htm, json, txt, xml, xsd, map, md, mp4

Miscellaneous

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.

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 has support for several JavaScript transpilers. See the list at the top of the page.

Mimosa's root/base JavaScript compile wraps the module compilers and provides functionality to support writing and cleaning up source maps for those compilers that create them.

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.

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 and 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), 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. To the right are the names of the libraries Mimosa places in vendor/javascripts directory.

Name Library Name
Handlebars handlebars
Emblem handlebars
Dust dust
Hogan hogan-template
Jade jade-runtime
Underscore underscore
Lodash lodash
EJS ejs-filters
ECO none
Ractive ractive

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 the libraries listed 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-documented also includes a commented out example for this configuration.

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

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

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-documented includes a commented out example.

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.

The file copying module handles copying files 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.

If your favorite meta-language or library is missing, file an issue and we'll look into adding support for it! Or you can create one yourself. Compilers are easy to create and there are already over 20 examples out there.

Want to create your own? The best place to start is with an existing compiler.

All of Mimosa's compiler modules get wrapped in a parent super-compiler. So, the CoffeeScript compiler gets wrapped with a more generic JavaScript compiler when you start Mimosa. The super-compilers interact with the compiler modules via a defined interface. You can see the interface at the bottom of the CoffeeScript compiler.

If the compiler you want to create doesn't neatly fit into JS/CSS/Template/Copy, you can use the Miscellaeous compiler. There isn't yet a Miscellaeous compiler, but you can see how to implement one with the sample Miscellaenous compiler project.