es6-library-boilerplate
Author libraries in ES6 for Node and the browser.
Features
- Author in ES6
- Export as ES5 & UMD
- Mocha-Chai-Sinon testing stack
- Unit tests that work in Node and in the browser
Getting Started
Place your code in src
. The primary file is index.js
(note:
the filename can be changed).
Run gulp build
to compile the source into a distributable format.
Put your unit tests in test/unit
. The gulp
command runs the tests.
Gulp
There are three primary Gulp tasks.
gulp
- Lint the library and tests, then run the unit testsgulp build
- Lint then build the librarygulp test:browser
- Build the library for use with the browser spec runner. Changes to the source will cause the runner to automatically refresh.
Browser Tests
The browser spec runner
can be opened in a browser to run your tests. For it to work, you must first run gulp test:browser
. This
will set up a watch task that will automatically refresh the tests when your scripts, or the tests, change.
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:
- It consumes code coverage reports, and provides a badge for the README
- It provides interesting stats on your library, if you're into that kinda thing
One or both of these items on the list can simply be ignored if you're uninterested in it. 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.
FAQ
When should I consider using this boilerplate?
You're authoring a library that exports a single file, and that one file exports a single variable.
When might I not want to use this boilerplate?
You can always use this boilerplate as inspiration, but it works best for smaller libraries. If you're building a full-scale webapp, you will likely need many more changes to the build system.
Are there examples?
Quite a few! Check them out on the wiki.
Customizing
This boilerplate is, to a certain extent, easily 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:
- Rename the file
- Update the value of
entryFileName
inconfig/index.json
I want to change the exported file name
- Update the value of
exportFileName
inconfig/index.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:
- Ensure that the variable you're exporting exists in your scripts
- Update the value of
exportVarName
inconfig/index.json
- Update the globals array in the
test/.jshintrc
file - Check that the unit tests have been updated to reference the new value
I want to change the destination directory
- Update the value of
destinationFolder
inconfig/index.json
My library depends on an external module
There are a few more files to update to add external modules.
- Install the module via
npm install --save THE_MODULE
- Load the module in the test setup file. Attach any exported variables to global object if you'll be using them in your tests.
- Update both
.jshintrc
files to include any new global variable that you have added - Add those same global variables to the
mochaGlobals
array inconfig/index.json