Configuration

The keys to the kingdom, when Mimosa's defaults aren't quite cutting it

When Mimosa starts up, it expects to find a mimosa-config.coffee or a mimosa-config.js file in current directory. The mimosa-config file configures all that Mimosa does.

How to get it?

There are two ways to be given a config file by Mimosa: with mimosa new and mimosa config. For mimosa new, the mimosa-config will be altered to match the selections made during project creation. For mimosa config only the modules are provided. Both commands, however, also output a mimosa-config-documented.coffee file which contains all of the documentation on the possible/default configuration items for the modules that are currently installed.

For both mimosa new and mimosa config, the mimosa-config file is a JavaScript file. However, if CoffeeScript is preferred, the file can be converted to .coffee and Mimosa will find it and use it.

Why is my config file so small?

One of Mimosa's goals was to have developers spending as little time fiddling with config as possible. The more time spent looking at config, the more time spent understanding it, and playing with it, then the less time is spent actually writing code. To that end, while highly configurable, Mimosa comes set up with a really sane set of defaults/conventions built-in.

While the delivered config file is small, the mimosa-config-documented.coffee file that Mimosa also provides is large and contains all the possible/default configuration items for the installed modules.

When you want to change the config...

First stop and consider if there is any way Mimosa can help. We'd rather build more smarts into Mimosa than to force more config maintenance. For instance, if you feel certain jshint options should be enabled by default for CoffeeScript applications, or another file extension should be added to the copy compiler, then let us know!

Profiles allow for overriding of mimosa-config settings via external config files. A project might have a "build" profile that is used for automated builds, and for those builds maybe certain modules aren't needed. For instance the "lint" module can be left out of the modules array.

Profiles are implemented as mimosa-config files. Any properties of a project's mimosa-config that need to be overridden would be the properties placed in a profile file.

By default, profile files should be located in a profiles/ directory at the root of a Mimosa project. This location can be overridden via the profileLocation property in the project's mimosa-config. profileLocation is relative to the root of the project.

Profiles can be used for the watch, build and clean commands. Each of those commands have a -P/--profile flag. Follow the flag with the name of the profile to use and Mimosa will pull that profile in and use it to override the settings in the mimosa-config. Ex: mimosa build -P build.

If necessary the root mimosa-config can be accessed in your profile. For more information, see this GitHub issue

Multiple Profiles

New with version 2.2.14 of Mimosa, multiple profiles can be provided at the command line. Ex: mimosa build -P foo#bar. Profiles are applied from left to right. So, in this case if the bar profile contains the same configuration as the foo profile, the bar profile information will overwrite foo.

Default Profiles

New with version 2.3.2 of Mimosa is the introduction of default profiles. Profiles are a powerful feature. Using a profile is easy enough, but if you have a set of profiles that you are constantly applying, you find yourself typing -P profileName quite a bit. Now you can keep a default profile in a `.mimosa_profile` file at the root of your project. This file, a \n-delimited list of profile names, will be the first profiles applied. You can also append -P profileName and those profiles will be applied last (and therefore override any settings in a default profile).

Mimosa Core Configuration

The following sections document Mimosa's core config. All Mimosa projects have this config to alter basic Mimosa behavior. Any configuration for your project not documented below belongs to a Mimosa module that you have installed into your project. If you are looking for configuration that isn't present here, for example, for your bower config or your require config, then you will want to check the GitHub repository for those modules.


Version Enforcement

These settings are useful on project teams, when, for example, features of a newly released Mimosa are used, and the team wants to enforce that everyone upgrade their Mimosa.

minMimosaVersion

minMimosaVersion: null,
requiredMimosaVersion: null

The minMimosaVersion setting allows the enforcing of a minimum allowed Mimosa version in order to start Mimosa with the given project. If a user has version 1.1.0 installed, and the minMimosaVersion is set to 1.1.5, when Mimosa is started, it will write an error to the log and exit. Until the version problem is cleared up, Mimosa will not start.

When set to null, which is the default, Mimosa will not perform any version checks.

requiredMimosaVersion

The requiredMimosaVersion setting allows the enforcing of specific Mimosa version in order to start Mimosa with the given project. If a user has version 1.1.0 installed, and the requiredMimosaVersion is set to anything else, then when Mimosa is started, it will write an error to the log and exit. Until the version problem is cleared up, Mimosa will not start.

When set to null, which is the default, Mimosa will not perform any version checks.


Module List

modules

The modules array informs Mimosa what Mimosa modules to use. Many Mimosa modules may be installed, both ones that come with Mimosa and ones installed on top of Mimosa. This setting lets Mimosa know which ones to use for a project. The defaults represent those modules that come with Mimosa out of the box without any additional installs. The mimosa- can be left off the name of modules as Mimosa will assume it.

If a module is included that is not installed, Mimosa will attempt to install it from NPM. This saves the extra step of doing a mod:install.

Also, this config allows for installing specific versions of modules. If a new module is added by name only, Mimosa installs the latest version. If a version if provided, Mimosa will install that specific version.

modules: [
  'copy'
  'jshint',
  'csslint',
  'server',
  'require',
  'minify-js',
  'minify-css',
  'live-reload',
  'bower'
]

The syntax for installing specific versions is moduleName@moduleVersion, for example web-package@0.2.0. Versions can be changed and toggled at will. Because Mimosa installs modules on startup, different versions of a module can be used per project and incur only the cost of the time it takes to run the install when you switch between projects.


File System Watching

watch

The watch section of the config contains information about what directories to watch, what files to ignore, and how fast to process added files.

watch.sourceDir

The sourceDir property is the path, either relative to the mimosa-config or absolute, where assets are located. This is the directory Mimosa will watch for changes to kick off the compiler workflow.

watch.compiledDir

The compiledDir property is the path, relative to the mimosa-config or absolute, where compiled assets will be delivered. If the compiledDir does not exist, Mimosa will create it. Mimosa will mimic the same folder/directory structure in the compiledDir that it finds in the sourceDir

watch: {
  sourceDir: "assets",
  compiledDir: "public",
  javascriptDir: "javascripts",
  exclude: [/[/\\](\.|~)[^/\\]+$/],
  throttle: 0,
  usePolling: true,
  interval: 100,
  binaryInterval: 300,
  delay: 0
}

watch.javascriptDir

Location of the JavaScript code inside the watch.sourceDir directory and therefore also the location of the compiled JavaScript in the watch.compiledDir. Note that there is not a watch.stylesheetsDir. Mimosa does not need to know where CSS is placed, so the directory containing CSS can be named anything.

watch.javascriptDir can be set to null if not building web applictions. If watch.javascriptDir is set to null inside a web application, Mimosa will error out in a non-graceful fashion, so be careful when using this setting.

watch.exclude

The exclude property is an array of strings and/or regexs that match paths to exclude from processing. Path strings can be relative to the sourceDir or absolute. String paths must include the file name. When a path string or a regex matches a file path, Mimosa will ignore the file. By default this property is set such that various dot and temp files are ignored.

watch.throttle

The throttle property represents how many files Mimosa will process every 100 milliseconds. Setting this property will slow down processing of file additions. This is necessary for very large projects with thousands of files. Mimosa processes them so fast that it quickly hits a system's open file limit. When this setting is set to 0, no throttling will take place. But if there are hundreds of files and EMFILE issues occur, play with the throttle. It may take a few minutes to get the throttle setting right, so that Mimosa is still processing files quickly, but not so quickly it crashes. NOTE: IfusePolling is set to false, this setting has no effect.

watch.usePolling

DO NOT turn usePolling off if you are on a *nix, you will crash with EMFILE issues. Windows users, read on: The usePolling setting determines whether or not system polling is the method by which Mimosa keeps track of project assets. Polling on large applications with many hundreds of files may cause Mimosa/node to eat up a lot of CPU. The first settings to play with are the intervals below, to see if you can slow the polling down to an amount that is satisfactory to use but that also doesn't eat up the CPU. Turning usePolling to false is a last option.

watch.interval

The interval setting, when usePolling is set to true, determines how frequent polling occurs for non-binary files. Tweak this number if you are having CPU issues.

watch.binaryInterval

The binaryInterval setting, when usePolling is set to true, determines how frequent polling occurs for binary files. Tweak this number if you are having CPU issues.

watch.delay

The delay setting forces Mimosa to pause for a number of milliseconds before processing a file. Use this if it seems Mimosa is processing a file before the file has been entirely written.


Vendor Scripts

vendor.javascripts

The location, relative to the watch.sourceDir, of the vendor scripts.

vendor.stylesheets

The location, relative to the watch.sourceDir, of the vendor stylesheets.

vendor: {
  javascripts: "javascripts/vendor",
  stylesheets: "stylesheets/vendor"
}

Core Template Config

For details on how templates work, check the Using Template Compilers documentation.

template.writeLibrary

By default many of Mimosa's template compilers will write an AMD wrapped version of the template compiler's client library as a convenience. If using common as a wrapType it will not. But there are cases when AMD is being used and a client library is not desired. In those cases set template.writeLibrary to false.

template.wrapType

By default Mimosa wraps compiled template files in an AMD-compliant define block. When wrapType is set to "none" Mimosa will not wrap the compiled template files and will also not write a wrapped client library for the micro-templater of choice. When wrapType is set to "common", CommonJS style requires and module.exports are used.

template: {
  writeLibrary: true,
  wrapType: "amd",
  nameTransform: "fileName",
  commonLibPath: null,
  outputFileName: "javascripts/templates",

-- OR instead of outputFileName --

  output: [{
    folders:[""],
    outputFileName:""
  }]
}

template.nameTransform

Mimosa provides some flexibility in the naming of compiled templates. template.nameTransform allows for configuring the naming of compiled templates. There are 4 possible settings.

template.commonLibPath

Valid when wrapType is 'common'. The commonjs path to the client library. Some libraries do not have clients therefore this is not strictly required when choosing the common wrapType

template.outputFileName

The path of the file all templates are compiled into. The path is relative to watch.sourceDir. If multiple templating languages are being used, instead of being a single string, this setting should be a map of Mimosa template compiler name to file path. Like hogan:"hogan-templates", dust:"dust-templates". See the modules tab for more info.

template.output

An alternate configuration to template.outputFileName, template.output allows for writing several compiled template files. This is ideal when using compiled templates across multiple pages as opposed to a single page web app. template.output and template.outputFileName cannot both be used at the same time.

template.output[].folders

All of the templates contained inside folders are compiled and bundled together. It is recursive, so any templates inside sub-folders are included as well. folders entries are relative to watch.sourceDir and must exist. If left a blank string, the folder used will be watch.sourceDir.

template.output[].outputFileName

template.output[].outputFileName is identical to template.outputFileName except it is scoped in this case to just the folder specified by the folder property. There is no default, so this property must be provided.


Logging

If Growl is installed and turned on, a Growl notification will be created for each failed or successful asset compile. In the event Growl gets too spammy, Growl notifications can be turned off for successful compiles or turned off entirely.

To allow Mimosa to use Growl, an extra library needs to be installed. For details on installation on your system, check out the node-growl page.

logger.info.enabled

Whether or not Info level logging is enabled.

logger.info.color

The color for Info level logging.

logger.warn.enabled

Whether or not WARN level logging is enabled.

logger.warn.color

The color for WARN level logging.

logger.success.enabled

Whether or not Success level logging is enabled.

logger.success.color

The color for Success level logging.

logger.error.enabled

Whether or not ERROR level logging is enabled.

logger.error.color

The color for ERROR level logging.

logger.debug.color

The color for Debug level logging.

logger.embedded.enabled

Whether or not embedded content in log messages is differently colored.

logger.embedded.color

The color for embedded content.

growl.enabled

Whether or not Mimosa will attempt to send Growl messages.

logger: {
  info: {
    enabled: true,
    color: null
  },
  warn: {
    enabled: true,
    color: 'yellow+bold'
  },
  success: {
    enabled: true,
    color: 'green'
  },
  error: {
    enabled: true,
    color: 'red+bold'
  },
  debug: {
    color: 'blue'
  },
  embeddedText: {
    enabled: true,
    color: 'cyan'
  },
  growl: {
    enabled: true,
    onStartup: false,
    onSuccess: true
  }
}

growl.onStartup

Controls whether or not to Growl when assets successfully compile/copy on startup. If there are 100 CoffeeScript files, and clean and watch are performed, there will be 100 successful compiles. This setting prevents growl messages for those successful compiles.

growl.onSuccess

Whether or not to Growl success log messages after startup.