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!

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.

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.

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.

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.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"
}

With Mimosa 2.0 the compilers section of the mimosa-config was removed. 2.0 externalized all of the compilers, so the compilers config now resides with each individual external compiler.

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.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.

  • 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.
  • A RegExp can be provided. That RegExp is applied on the filePath string from above to remove any unwanted pieces of text from the string. The RegExp is used as part of a string.replace
  • A function can be provided. That function is passed the filePath from above. The function must return a string that is the desired name of the template.

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

-- OR instead of outputFileName --

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

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.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 compilers tab for more info.

template.handlebars

With Mimosa 2.0 the handlebars config has been removed from the template config. Mimosa 2.0 externalized all of the compilers, so the handlebars config now resides with the two new handlebars and ember-handlebars compilers.

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.

copy

The copy config block contains configuration for the copy "compiler". For more information on the copy "compiler", see the compilers tab.

copy.extensions

copy.extensions is an array of strings representing the extensions for the files that Mimosa will copy from the watch.sourceDir to the watch.compiledDir. Mimosa will still run various workflow steps (like linting and AMD path verification) against certain copied assets. If you find yourself editing this list, consider filing an issue to get your extension added to the defaults.

copy: {
  extensions: ["js","css","png","jpg","jpeg","gif","html","eot","svg","ttf","woff","otf","yaml","kml","ico","htc","htm","json","txt","xml","xsd","map","md","mp4"],
  exclude: []
}

copy.exclude

An array of string paths or regexes that match files to exclude from copying. Paths should be relative to the watch.sourceDir or absolute. String paths must include the file name.

server

Configuration for embedded and/or delivered server. Many of the settings below are targeted primarily at configuring Mimosa's embedded server. When running a node server, the settings can be either used or ignored. That server can set its own port, for instance, rather than use the port passed by Mimosa. But the server and view code delivered via mimosa new will reference the settings below.

server.defaultServer

server.defaultServer contains configuration for the server inside Mimosa.

server.defaultServer.enabled

server.defaultServer.enabled determines whether Mimosa will start a default server or attempt to use a server in the project. When set to true, Mimosa will run its own embedded Express.

server.defaultServer.onePager

server.defaultServer.onePager lets Mimosa know if a project is a one or multi page application. This effects how Mimosa's embedded server handles routing. See the server page for more details

server: {
  defaultServer: {
    enabled: false,
    onePager: false
  },
  path: 'server.js',
  port: 3000,
  base: '',
  views: {
    compileWith: 'jade',
    extension: 'jade',
    path: 'views',
    options: {}
  }
}

server.path

When defaultServer.enabled is set to false, server.path is the path to the server code. The path can be relative to the root of the application or absolute. The server code at server.path must export a startServer function. Mimosa will pass that method a copy of the mimosa-config, including all the defaults for each setting and including extra fields inserted by Mimosa upon startup. startServer will also be passed a callback that it must execute when complete. As of v2.1.7 both 'server.coffee' and 'server.js' are valid defaults. If server.path is not provided, Mimosa will look for both files before providing a validation error.

server.port

The port on which Mimosa starts the server.

server.base

The base path of the application. By default this is set to blank, so the application is served up at http://localhost:3000, but set base to 'app' and the application would be served at http://localhost:3000/app.

server.views

Configuration for the views.

server.views.compileWith

The language/library of the server views. Valid values: jade, hogan, ejs, dust and handlebars.

server.views.extension

Extension of server views.

server.views.path

The path to server views. The path can be either absolute or relative. If server.defaultServer.enabled is set to true, server.views.path is relative to the root of the project. If server.defaultServer.enabled is set to false, server.views.path is relative to server.path.

server.views.options

Options to pass to any views being served by Mimosa's default server.

bower

Root level container for Bower configuration.

bower.watch

When bower.watch is set to true, Mimosa will watch the bower.json for changes, and when the file changes, run a Bower install.

bower.bowerDir

Container for configuration for how to handle the directory where Bower first places its assets before Mimosa copies them to their final destination.

bower.bowerDir.path

The path to where mimosa-bower will initially install Bower assets before moving the key assets into the watch.sourceDir. This is a string and is relative to the root of the project.

bower.bowerDir.clean

A flag to indicate whether or not to remove temporary bower assets after install. Bower downloads entire GitHub repositories, so cleaning them keeps your project from having those be kept around.

bower: {
  watch:true,
  bowerDir: {
    path: ".mimosa/bower_components",
    clean: true
  },
  copy: {
    enabled: true,
    trackChanges: true,
    outRoot: null,
    exclude:[],
    unknownMainFullCopy: false,
    mainOverrides: {},
    strategy: "packageRoot",
    forceLatest: true,
    pathMod: []
  }
}

bower.copy

Container for properties that instruct mimosa-bower how to go about copying assets to their eventual destination.

bower.copy.enabled

A flag to indicate whether or not to copy assets out of the bowerDir.path and into watch.sourceDir

bower.copy.trackChanges

When set to true, mimosa-bower will keep track of your bower.json and mimosa-config bower configuration and kick off installs if it detects changes. When set to false, bower's default checking is used. The Bower default checking is based on the contents of bowerDir.path. If bowerDir.clean is true and trackChanges is false, mimosa-bower will not perform installs during watch and build because installs would occur every time Mimosa starts up.

bower.copy.outRoot

A string path to append to the vendor directories before copying in assets. All copied assets would go inside this directory. Example: "bower-managed". null means no outRoot is applied. null is the default.

bower.copy.exclude

An array of string paths or regexes that match files to exclude from copying. Paths should be relative to the bowerDir.path or absolute. String paths must include the file name.

bower.copy.unknownMainFullCopy

A boolean that when set will force the copy of all Bower module assets into the vendor output directory for the module. This will likely copy a lot of undesirable assets, but if that isn't a problem, setting this property is a quick way to get files copied over without the hassle of configuring mainOverrides (below).

bower.copy.mainOverrides

Occasionally bower packages do not clearly indicate what file is the main library file. In those cases, mimosa-bower cannot find the main files to copy them to the vendor directory. json2 is a good example. mainOverrides allows for setting which files should be copied for a package. The key for this object is the name of the package. The value is an array of path strings representing the package's main files. The paths should be relative to the root of the package. For example: {"json2":["json2.js","json_parse.js"]}. The paths can also be to directories. That will include all the directory's files. mainOverrides packages can also be provided an object in addition to string paths. The object maps input paths to output paths and allow for specific placement of files and folders. Ex {"json2":[{"json2.js":"json-utils/json2.js"}]. In this case the json2.js file will be placed in json-utils/json2.js in the vendor.javascripts folder. If a file is provided as opposed to a directory, the output path must specify the output file name. Any directories copied in this way are copied entirely without manipulation of the folder structure.

See this gist for a detailed and explained real world mainOverrides example.

bower.copy.strategy

The copying strategy, a string. vendorRoot places all files at the root of the vendor directory. packageRoot places the files in the vendor directory in a folder named for that package. none will copy the assets into the vendor directory without modification. strategy can also be an object with keys that match the names of packages and values of strategy types. When using a strategy object, the key of * provides a default strategy. If only 2 of 10 packages are specified in the object, the rest get the * strategy. If no * is provided, packageRoot is the assumed default.

bower.copy.forceLatest

forceLatest is a means to quickly fix any problems with library version collisions. If you want to install the latest jquery, but one of your other libraries wants to install an older version the install will fail. This flag will ensure the the latest version is selected and the Bower install will continue. When the forceLatest results in a selection, a warning message is logged with the details of which version was picked and which versions were not.

bower.copy.pathMod

pathMod can be an array of strings or regexes. It is used to strip full pieces of a path from the output file when the selected strategy is none or a mainOverrides object is used. If a Bower package script is in packageName/lib/js/foo.js and pathMod is set to ["lib", "js"] the output path would have lib and js stripped.

require

Mimosa's configuration for AMD/RequireJS path verification and the r.js optimizer.

require.exclude

The exclude setting is an array of either string paths (absolute or relative) or regexes that when matching a file will keep that file from being processed by the require module. This can be used to keep files from being considered main modules to be used for processing if require infers incorrectly. String paths must include the file name.

require.commonConfig

Location of common RequireJS configuration that is used across multiple pages/modules. See the RequireJS multi-page application example on GitHub for an example of using common configuration.

require.tracking

Settings for mimosa-require tracking. When enabled mimosa-require makes a record of its dependency information on the file system. This provides faster mimosa watch startup times as Mimosa does not need to process every JavaScript file to build the mimosa-require dependency information.

require.tracking.enabled

When set true mimosa-require will keep tracking information cached on the file system. When set to false mimosa-require will force Mimosa to recompile all the JavaScript. This currently defaults to false while it is being tried out but will default to true in the near future.

require: {
  exclude:[],
  commonConfig:"common",
  tracking: {
    enabled: true,
    path: ".mimosa/require/tracking.json"
  }
  verify: {
    enabled: true,
    plugins: {
      css:"css",
      hbs:"hbs"
    }
  }
  optimize : {
    modules: null,
    moduleCachingPath: ".mimosa/require/moduleCaching",
    inferConfig:true,
    overrides:{}
  }
}

require.tracking.path

The path to the tracking file.

require.verify

Settings for AMD/RequireJS path verification.

require.verify.enabled

Whether or not Mimosa will perform AMD/RequireJS path verification.

require.verify.plugins

mimosa-require will verify plugin paths that are listed as dependencies. It does not keep track of plugins otherwise. Plugins are provided by giving the plugin prefix as the key and the extension of the plugin files as a value. "css" and "hbs" are provided as default plugins. If you add more to this list, consider submitting an issue to have it added as a default.

require.optimize

Settings for asset optimization via the r.js optimizer.

require.optimize.modules

Use this if building a modules-based require.js application. This is a straight pass-through of the typical require.js modules config.

require.optimize.moduleCachingPath

This setting is only valid when running a modules-based project. Mimosa keeps some files cached for re-running during mimosa watch. This path is where the caching takes place.

require.optimize.inferConfig

Mimosa infers many r.js optimizer settings. Set inferConfig to false to make Mimosa not do that. Check out the Optimization tab to see what inferences Mimosa makes for r.js execution.

require.optimize.overrides

Used to make tweaks to the r.js configuration for asset optimization, uncomment this line and add the r.js config as new parameters inside the require.optimize.overrides object. To just unset a Mimosa defaults, set the property to null. require.optimize.overrides can also be a function. That function is passed the full inferred r.js config for the module being optimized. This provides the opportunity to amplify the inferred config rather than just replace it.

minifyJS

The minifyJS config block contains configuration for JavaScript minification/compression via uglify using the --minify flag. For more information on minification, see the optimization tab.

minifyJS.exclude

minifyJS.exclude contains an array of regexs and/or strings that match paths to exclude from minification. String paths can be either relative to the watch.compiledDir or absolute. String paths must include the file name. Any file possessing ".min." in its name, like jquery.min.js, is assumed to already be minified so it will be ignored by default.

minifyJS: {
  exclude:[/\.min\./],
  mangleNames:true
}
minifyCSS: {
  exclude:[/\.min\./],
  options:{ 
    processImport: false
  }
}

minifyJS.mangleNames

minifyJS.mangleNames, when set to false will not alter variable names when JavaScript code is minified.

minifyCSS

The minifyCSS config block contains configuration for CSS minification/compression via clean-css using the --minify flag. For more information on minification, see the optimization tab.

minifyCSS.exclude

minifyCSS.exclude contains an array of regexs and/or strings that match paths to exclude from minification. String paths can be either relative to the watch.compiledDir or absolute. String paths must include the file name. Any file possessing ".min." in its name, like bootstrap.min.css, is assumed to already be minified so it will be ignored by default.

minifyCSS.options

minifyCSS.options contains options for the clean-css package.

minifyCSS.options.processImport

minifyCSS.options.processImport is a default setting for the minify-css/clean-css module that prevents @import statements from being removed.

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.

jshint

jshint

Settings for JS hinting, including what files should be linted and rule overrides to use when running linting. For more on linting, see the Utilities tab.

jshint.exclude

Files to exclude from jshint. This setting is an array and can be comprised of strings or regexes. Strings are paths that can be relative to the watch.compiledDir or absolute. String paths must include the file name.

jshint: {
  exclude:[],
  compiled: true,
  copied: true,
  vendor: false,
  jshintrc: ".jshintrc",
  rules: {}
}

jshint.compiled

When this property is set to true, Mimosa will execute jshint on the successful compile of an asset to JavaScript.

jshint.copied

When this property is set to true, Mimosa will execute jshint on the successful copy of a JavaScript asset.

jshint.vendor

When this property is set to true, Mimosa will execute jshint on the successful copy of a vendor JavaScript asset.

jshint.jshintrc

Location of a .jshintrc file if one exists. Mimosa will look up the file structure in an attempt to find this file, eventually stopping at the file system root.

jshint.rules

Add jshint overrides as key/value pairs underneath this property.

csslint

csslint

Settings for CSS linting, including what files should be linted and rule overrides to use when running linting. For more on linting, see the Utilities tab.

csslint.exclude

Files to exclude from linting. This setting is an array and can be comprised of strings or regexes. Strings are paths that can be relative to the watch.compiledDir or absolute. String paths must include the file name.

csslint: {
  exclude:[],
  compiled: true,
  copied: true,
  vendor: false,
  rules: {}
}

csslint.compiled

When this property is set to true, Mimosa will execute csslint on the successful compile of an asset to CSS.

csslint.copied

When this property is set to true, Mimosa will execute csslint on the successful copy of a CSS asset.

csslint.vendor

When this property is set to true, Mimosa will execute csslint on the successful copy of a vendor CSS asset.

csslint.rules

Add csslint overrides as key/value pairs underneath this property.

liveReload.enabled

This property determines whether or not Live Reload is enabled. When Live Reload is enabled, a few javascript files are added to the layout of the dev version of the app. See the Utilities tab to read more on this functionality.

liveReload: {
  enabled: true,
  additionalDirs:["views"]
}

liveReload.additionalDirs

A list of additional directories to cause Live Reload to refresh the browser. Paths in the array can be absolute or relative to the root of the project. By default this is set to ["views"], which means a change to anything in the views directory will cause the browser to refresh.