generator-babel-boilerplate

A Yeoman generator to author libraries in ES2015 (and beyond!) for Node and the browser.

Features

✓ Author in ES2015 (including the unit tests)
✓ Export as ES5 & UMD
✓ Mocha-Chai-Sinon testing stack
✓ Unit tests that work in Node and in the browser

Installation

Install yo and this generator globally.

npm install -g yo generator-babel-boilerplate

Using Yeoman

Navigate to the directory you'd like to use for your project, then run yo babel-boilerplate.

Answer a few questions, and your project will be scaffolded.

Basic Guide

Write your code in src. The entry file is what you named the project in kebab case (although the filename can be changed).

Run npm run build to compile the source into a distributable format.

Put your unit tests in test/unit. The npm test command runs the tests using Node. If your library / tests require the DOM API, see the test/setup/node.js file.

npm Scripts

• npm test - Lint the library and tests, then run the unit tests
• npm run lint - Lint the source and unit tests
• npm run watch - Continuously run the unit tests as you make changes to the source and test files themselves
• npm run test-browser - Build the library for use with the browser spec runner. Changes to the source will cause the runner to automatically refresh.
• npm run build - Lint then build the library
• npm run coverage - Generate a coverage report

Browser Tests

The browser spec runner can be opened in a browser to run your tests. For it to work, you must first run npm run test-browser. This will set up a watch task that will automatically refresh the tests when your scripts, or the tests, change. The spec runner file is located at test/runner.html: open it in your browser to run tests.

Code Climate

This library is set up to integrate with Code Climate. If you've never used Code Climate, then you might be wondering why it's useful. There are two reasons:

1. It consumes code coverage reports, and provides a coverage badge for the README
2. It provides interesting stats on your library, if you're into that kinda thing

Either of these items on the list can simply be ignored if you're uninterested in them. Or you can pull Code Climate out entirely from the boilerplate and not worry about it. To do that, update the relevant Gulp tasks and the Travis build.

If you'd like to set up Code Climate for your project, follow the steps here.

Linting

This boilerplate uses ESLint to lint your source. To change the rules, edit the .eslintrc files in the root directory, respectively.

Given that your unit tests typically follow different rules from your library code, it makes sense to lint them against a separate ESLint configuration. For this reason, a separate, unit-test specific .eslintrc can be found in the test directory.

FAQ

{
  "presets": ["latest"],
  "plugins": [
    "add-module-exports",
    "transform-es2015-modules-umd"
  ]
}

Troubleshooting

Accessing the window or DOM in tests isn't working

The tests run in Node, which has neither a window nor the DOM. To access the DOM, you'll need to do a bit of configuration. The quickest solution would be to add JSDom. The test setup file has a comment on the easiest way to get JSDom up-and-running (it takes all of 10 seconds).

Alternatively, you could set up PhantomJS to run the tests in a headless webkit environment, or set up Karma to run the tests in real browsers.

Customizing

This boilerplate is, to a degree, customizable. To make changes, find what you're looking to do below and follow the instructions.

I want to change the primary source file

The primary source file for the library is src/index.js. Only the files that this file imports will be included in the final build. To change the name of this entry file:

1. Rename the file
2. Update the value of entryFileName in package.json under babelBoilerplateOptions

I want to change the destination file name or directory

1. Update main in package.json

I want to change what variable my module exports

MyLibrary is the name of the variable exported from this boilerplate. You can change this by following these steps:

1. Ensure that the variable you're exporting exists in your scripts
2. Update the value of exportVarName in package.json under babelBoilerplateOptions
3. Check that the unit tests have been updated to reference the new value

I don't want to export a variable

When prompted for the name of the library's main variable, leave the response empty.

My library depends on an external module

Install the module and use it in your scripts like usual. Then, go into the Gulpfile and add the externals to the Webpack build options.

If you want to access the module itself in your unit test files, you will need to set up the test environment to support the module. To do this:

1. Load the module in the test setup file.
2. Add any imported variables to globals object in the test globals JSON.