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, or in one of the directories above the current directory. The mimosa-config file configures all that Mimosa does.
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 the entire config file is commented out.
For both mimosa new and mimosa config, the mimosa-config file is a CoffeeScript file. However, if JavaScript is preferred, the file can be converted to a .js and Mimosa will find it and use it. Just have to make sure the file is valid JavaScript. CoffeeScript comments (#, ###) will need to be changed to JavaScript comments (//, /*...*/). Curly brackets and commas will need to be added as well.
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, and the less time spent actually writing code. To that end, while highly configurable, Mimosa comes set up with a really sane set of defaults/conventions built-in.
However, rather than deliver an empty text file for the config, the mimosa-config comes with all of the configurable options listed out and explained, but commented out. Each commented out option also lists its default. Options, defaults, and explanation...when the config file needs to be changed, everything is right there in the file.
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 maintainenance. 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!
But if, for instance, you just don't want compiled code in a directory named public, make sure to uncomment the right lines all the way back to the root of the config. Don't just uncomment the compiledDir, uncomment compiledDir and watch.
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 0.7.0 installed, and the minMimosaVersion is set to 0.7.1, 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.
minMimosaVersion: null
When set to null, which is the default, Mimosa will not perform any version checks.
This is 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.
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.
modules: ['lint', 'server', 'require', 'minify', 'live-reload']
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. 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
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. 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.
Many compilers have compiler specific configuration that is not listed here. Checkout the Compilers page for more information.
The compilers.extensionOverrides config block contains nothing by default. This property allows certain extensions to be processed by a specific compiler. Each Mimosa compiler is already configured to process files with certain extensions, but this configuration allows those extensions to be changed. To use this, map a compiler name to an array of extensions. For example, extensionOverrides:{coffee: ["coff", "coffee"]} will add the "coff" extension to the already-default "coffee" extension. The compilers.extensionOverrides setting can also be used to turn a compiler off if its behavior isn't desired. If CoffeeScript should not be compiled, the CoffeeScript compiler should be turned off with extensionOverrides:{coffee: null}
compilers: extensionOverrides:
The object for template configuration. If this is set to null the template compilers are not intantiated. This is a quick and easy way to disable all template compilation, if, for instance, you wanted to add template extensions to be copied rather than be compiled.
By default Mimosa wraps compiled template files in an AMD-compliant define block. When amdWrap is set to false Mimosa will not wrap the compiled template files and will also not write a wrapped client library for the micro-templater of choice.
The path of the file all templates are compiled into. The path is relative to watch.javascriptDir. 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: amdWrap: true outputFileName: "templates" helpers: ["app/template/handlebars-helpers"] ember: enabled:false path:"vendor/ember" -- OR instead of outputFileName -- output: [{ folders:[""] outputFileName:"" }]
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.javascriptDir and must exist. If left a blank string, the folder used will be watch.javascriptDir.
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.
The copy config block contains configuration for the copy "compiler". For more information on the copy "compiler", see the compilers tab.
copy: extensions: ["js","css","png","jpg","jpeg","gif","html","eot","svg","ttf","woff","otf","yaml","kml","ico","htc","htm","json","txt","xml","xsd","map"]
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.
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 contains configuration for the server inside Mimosa.
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: enabled: false onePager: false path: 'server.coffee' port: 3000 base: '' views: compileWith: 'jade' extension: 'jade' path: 'views'
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
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.
The port on which Mimosa starts the server.
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.
Configuration for the views.
The language/library of the server views. Valid values: jade, hogan, ejs, and handlebars.
Extension of server views.
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.
Mimosa's configuration for AMD/RequireJS path verification and the r.js optimizer.
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.
Settings for AMD/RequireJS path verification.
require: commonConfig:"common" verify: enabled: true optimize : inferConfig:true overrides:
Whether or not Mimosa will perform AMD/RequireJS path verification.
Settings for asset optimization via the r.js optimizer.
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.
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.
The minify config block contains configuration for non-require minification/compression via uglify using the --minify flag. For more information on minification, see the optimization tab.
minify: exclude:[/\.min\./]
minify.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. Any file possessing ".min." in its name, like jquery.min.js, is assumed to already be minified so it will be ignored by default.
Settings for whether and when to send Growl notifications. By default any error in compilation will send a Growl message, and turning that off is not configurable.
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 Growls for those successful compiles.
growl: onStartup: false onSuccess: javascript: true css: true template: true copy: true
Various settings controlling whether or not to send Growl messages when tasks are successful post-startup.
Controls whether or not to get a Growl message upon successful compilation of JavaScript meta-language files.
Controls whether or not to send a Growl message upon successful compilation of CSS meta-language files.
Controls whether or not yto send a Growl message upon successful compilation of template file(s).
Controls whether or not to send a Growl message upon successful copying of copied assets, like images, plain JavaScript, and plain CSS.
Settings for CSS and JS linting/hinting, including what files should be linted and rule overrides to use when running linting. For more on linting, see the Utilities tab.
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.
Settings for assets Mimosa has compiled, like CoffeeScript or Stylus.
When this property is set to true, Mimosa will execute jshint on the successful compile of an asset to JavaScript.
When this property is set to true, Mimosa will execute csslint on the successful compile of an asset to CSS.
Settings for assets Mimosa has copied, like plain JavaScript and CSS.
lint: exclude:[] compiled: javascript:true css:true copied: javascript: true css: true vendor: javascript: false css: false rules: jshintrc: ".jshintrc" javascript: css:
When this property is set to true, Mimosa will execute jshint on the successful copy of a JavaScript asset.
When this property is set to true, Mimosa will execute csslint on the successful copy of a CSS asset.
Settings for vendor assets, both vendor CSS and vendor JS.
When this property is set to true, Mimosa will execute jshint on the successful copy of a vendor JavaScript asset.
When this property is set to true, Mimosa will execute csslint on the successful copy of a vendor CSS asset.
All hints/lints come with default rules built in. Override those with this setting.
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.
Add jshint overrides as key/value pairs underneath this property.
Add csslint overrides as key/value pairs underneath this property.
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"]
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.