Configuration explained & Mimosa core's configuration options
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.
Executing mimosa new and creating a new project will get you a good starter mimosa-config.
Or you can start with an empty config. Create a file named mimosa-config.js inside the directory where you wish to start a project. Inside that file, place the following configuration:
exports.config = {
"modules": []
}The next step is to tweak the configuration to match your project, or your project to match Mimosa's defaults (see below). Then, pick the modules you want and off you go!
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.
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 "jshint" 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. Other commands may support profiles, check the module documentation for any modules that introduce commands.
If necessary the root mimosa-config can be accessed in your profile. For more information, see this GitHub issue
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.
New with version 2.3.2 of Mimosa is the introduction of default profiles. 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. Inside this file should be a \n-delimited list of profile names. You can also append -P profileName and those profiles will be applied last (and therefore override any settings in a default profile).
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.
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: 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.
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.
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.
modules: [ 'copy' 'jshint', 'csslint', 'server', 'require', 'minify-js', 'minify-css', 'live-reload', 'bower' ]
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.
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.
The watch section of the config contains information about what directories to watch, what files to ignore, and how fast to process added files.
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: {
sourceDir: "assets",
compiledDir: "public",
javascriptDir: "javascripts",
exclude: [/[/\\](\.|~)[^/\\]+$/],
throttle: 0,
usePolling: true,
interval: 100,
binaryInterval: 300,
delay: 0
}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
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.
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.
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.
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.
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.
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.
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.
The location, relative to the watch.sourceDir, of the vendor scripts.
vendor: {
javascripts: "javascripts/vendor",
stylesheets: "stylesheets/vendor"
}The location, relative to the watch.sourceDir, of the vendor stylesheets.
This configuration is the core template config that all template compilers inherit and use. For details on how templates work, check the Using Template Compilers documentation.
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: {
writeLibrary: true,
wrapType: "amd",
nameTransform: "fileName",
commonLibPath: null,
outputFileName: "javascripts/templates",
-- OR instead of outputFileName --
output: [{
folders:[""],
outputFileName:""
}]
}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.
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.
fileName (default), this option results in the name of the file being the name of the template.filePath, this makes the name of the template the path of the file with 1) the watch.javascriptDir chopped off, 2) the slashes forced to /, and 3) the extension removed. No leading slash.filePath string from above to remove any unwanted pieces of text from the string. The RegExp is used as part of a string.replacefilePath from above. The function must return a string that is the desired name of the template.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
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.
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.
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 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.
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 instlled. For details on installation on your system, check out the node-growl page.
Whether or not Info level logging is enabled.
The color for Info level logging.
Whether or not WARN level logging is enabled.
The color for WARN level logging.
Whether or not Success level logging is enabled.
The color for Success level logging.
Whether or not ERROR level logging is enabled.
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
}
}The color for ERROR level logging.
The color for Debug level logging.
Whether or not embedded content in log messages is differently colored.
The color for embedded content.
Whether or not Mimosa will attempt to send Growl messages.
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.
Whether or not to Growl success log messages after startup.