wework / universal-npm-starter

Boilerplate for a NPM package for the node and browser using ES2015

universal-npm-starter

Boilerplate for a NPM package for the node and browser

Introduction

Replace this with your package's details!

Starter Intro

This is a boilerplate npm module that can be used to create a universal JavaScript module for node and browser runtimes. It uses rollup to bundle ES2015 code.

The implementation in this boilerplate generates a module thats is distributed perfectly symmetrically, meaning the exact same code is bundled for and executed in node and the browser.

This toolchain can also generate an asymmetrical package with runtime-specific bundles. This involves a few steps:

• modifying the the rollup config
• updating package.json with a browser property
• creating browser and node entry files
• maintaining API contracts between all entry files

See we-js-logger for an example of an asymmetrical package.

Usage

Clone this repo and replace the code in the src/ and test/ directories with your module. Make it your own. PRs are always welcome :)

Testing

Tests are run via mocha in node, and via karma, webpack and mocha for browsers (PhantomJS by default, but Karma is quite configurable).

This package is also preconfigured for Travis and Sauce Labs. To enable this:

1. Setup travis-ci for your repository
2. Add SAUCE_USER_NAME and SAUCE_ACCESS_TOKEN keys to the travis job

Examples

This boilerplate was developed while creating a few modules at WeWork:

• https://github.com/wework/env-universal
• https://github.com/wework/we-js-logger
• https://github.com/wework/express-universal-query-validator

Development

1. Checkout this repo
2. Run yarn
3. Make changes in a feature branch and open a PR to master

In lieu of a formal style guide, please:

• follow the conventions present in the codebase
• respect the linter
• keep tests green
• maintain test coverage

Installing an EditorConfig plugin is also nice.

npm scripts

Target	Behavior
yarn test	Runs tests in browser and node runtimes
yarn tdd	Runs tests, bundles and re-runs on file changes
yarn test:coverage	Runs tests and outputs a code coverage report to /coverage
yarn test:ci	Runs tests, outputs code coverage
yarn lint	(Run as a git pre-commit hook) Runs eslint
yarn docs	Generates API.md from JSDoc comments in /src
yarn security-scan	(Run as a git pre-push hook) Checks npm dependencies for security vulnerabilities
yarn release <version>	Generates a changelog, updates package version, tags and pushes via np. This should only be run on an up-to-date master by a maintainer of this package. Version can be a semver level: `patch

yarn run will list all npm scripts