installation.md

Installation

1. Up and running
2. Strict mode
3. Optional dependencies

Up and running

The easiest way to grab Microcosm is through npm:

npm install --save microcosm

From there, we recommend using a tool like Webpack to bundle your code and pull in dependencies from npm.

If you have never heard of Webpack, fantastic! Now's a great time to check it out. Webpack's excellent getting started guide covers everything you need to know before getting started.

Strict mode

Microcosm ships with a "strict mode", this is a special version of Microcosm that includes development-only assertions. These help to avoid common mistakes and ensure correct usage of Microcosm APIs. Assertions do not ship with the standard version of Microcosm. They are totally opt in.

Enable assertions by pointing to microcosm/strict in your application:

import Microcosm from 'microcosm/strict/microcosm.js'

However, this is hardly ideal. We recommend using a Webpack alias to automatically point to the strict version of Microcosm whenever you import it:

// webpack.config.js
module.exports = {
  // ...
  resolve: {
    alias: {
      microcosm: 'microcosm/strict'
    }
  }
  // ...
}

How do I remove assertions in production?

We recommend switching a Webpack alias between environments. Drawing from the prior example:

// webpack.config.js
var isProduction = process.env.NODE_ENV !== 'development'

module.exports = {
  // ...
  resolve: {
    alias: {
      microcosm: isProduction ? 'microcosm' : 'microcosm/strict'
    }
  }
  // ...
}

Optional dependencies

Microcosm actions can be described as generators. This is a new JavaScript feature available in JS2015, which does not have wide support.

This is an advanced feature. There is no need to include a polyfill for generators if you do not use them. We recommend using Babel with the regenerator polyfill available through babel-polyfill.