mimosa-bower

Overview

This module provides Bower support to Mimosa. It allows for installing of Bower packages and moving of those packages to the appropriate location in a Mimosa application. This module is targeted for the 1.0 release of Bower.

For more information regarding Mimosa, see http://mimosajs.com

For more information regarding Bower, see http://bower.io

Note: Version 0.14.0 or higher of Mimosa is required to use this module.

Usage

Run mimosa mod:install mimosa-bower to install this module into your global Mimosa install.

To install into a single project, add 'bower' to your list of modules. Mimosa will install the module from NPM for you when you start up Mimosa.

Functionality

When mimosa bower, mimosa watch or mimosa build are run, mimosa-bower will assess whether or not any packages need to be installed. mimosa-bower installs packages to the bower.bowerDir.path directory, by default .mimosa/bower_components.

If bower.copy.trackChanges is set to true (the default), mimosa-bower keeps track of two artifacts to help it determine if installs need to occur. First, it keeps track of the bower.json that was last used for an install. If the current bower.json is different, an install will be executed. Second, mimosa-bower keeps track of the bower section of your project's mimosa-config for the last install. If it changes, an install will be executed.

If bower.copy.trackChanges is set to false and bower.bowerDir.clean is set to false, Bower 1.0's default processing will check to see if an install is necessary based on the contents of the bower.bowerDir.path. If it detects that nothing has changed, no install will be run.

If bower.copy.trackChanges is set to false and bower.bowerDir.clean is set to true (not recommended), then mimosa-bower has no way to determine if an install is necessary so mimosa-bower does not register itself to be run during mimosa watch and mimosa build. In this case it must be executed using the mimosa bower command.

If any packages are installed, mimosa-bower then moves them into the vendor directories as indicated by Mimosa's vendor config introduced with Mimosa 0.14.0. The bower.copy.strategy determines how the files are copied over. They can be copied to the root of the vendor directory (vendorRoot), to the root of the component directory (packageRoot, the default), or can be copied keeping the entire folder structure intact, none.

mimosa-bower requires a valid bower.json at the root of project (in the same directory as mimosa-config).

If mimosa-bower encounters any version collisions, it will error out and indicate what those collisions are.

If mimosa-bower cannot identify the main file for a package because it hasn't been provided by the package author mimosa-bower will indicate that via a console log message. The bower.copy.mainOverrides can be used to indicate which files from the package are to use used.

New Commands

The following commands are added to Mimosa when mimosa-bower is included in a project.

bower & bower:install

bower and bower:install are identical commands. These commands provide one off access to Bower installs without kicking off watch or build. If bower.bowerDir.clean is set to true, this command is the only way to install Bower dependencies.

bower:clean [-c/--cache]

bower:clean will remove all of the installed dependencies from their target directories in the vendor folder. It will also clean up any Bower package related folders that then become empty. Finally it will clean up the bower.bowerDir.path folder, removing all the temporary assets.

bower:clean -c or bower:clean --cache, in addition to cleaning up installed dependencies, will also clean the Bower cache. This often is necessary when Bower updates, or if packages get updated without new versions.

Default Config

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

• bowerDir.path: string, the path to where mimosa-bower will initially install bower assets before moving the key assets into the watch.sourceDir
• bowerDir.clean: boolean, whether or not to remove temporary bower assets after install.
• copy.enabled: boolean, whether or not to copy assets out of the bowerDir.path and into watch.sourceDir
• 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.
• 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.
• copy.exclude: An array of string paths or regexes. Files to exclude from copying. Paths should be relative to the bowerDir.path or absolute.
• 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.
• copy.strategy: string, the copying strategy. "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.
• copy.forceLatest: forceLatest is a means to quickly fix any problems with library versions. 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. 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.
• copy.pathMod: pathMod can be an array of strings or a regexes. It is used to strip full pieces of a path from the output file when the selected strategy is "none" or a pathOverride 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. Feel free to suggest additions to this based on your experience!

Alternate Config

bower:
  copy:
    mainOverrides:
      foundation: [
        "js/foundation"
        {"scss":"foundation"}
      ]
    strategy:
      "*": "packageRoot"
      "jquery": "vendorRoot"
      "requirejs": "vendorRoot"

• Only default overrides are shown.
• This shows the alternate strategy configuration using specific strategy-to-package mappings.
• It also shows the alternate mainOverrides configuration, with the foundation package's js/foundation folder being pulled in according to the "*" strategy (packageRoot), and the foundation/scss folder being pulled into a foundation folder and otherwise left entirely in tact without any path manipulations.