How to write an open source JavaScript library

study notes taken from the egghead How to Write an Open Source JavaScript Library course.

Getting started

npm init set

$ vim ~/.npmrc

init-author-name=Joe Doe
init-author-email=user@example.com
init-author-url=https://github.com/joe
init-license=MIT
save-exact=true

$ npm adduser

$ npm init

name: (lab) lab-starwars-names
version: (1.0.0)
description: Get random Star Wars names
entry point: (index.js) src/index.js
test command:
git repository: (https://github.com/j1wu/lab.git)
keywords: random star wars
license: (MIT)

all the source code at this point can be found at this commit

A quick test

$ node
> var lib = require('./src/index.js');
undefined
> lib.all

Push to Github repo.

Public to npm

$ npm publish
$ npm info lab-starwars-names

Releasing a version to Github

Tag then push

$ git tag 1.0.0
$ git push --tags

Super Awesome Initial Release

Releasing a new version to npm

Make the code changes
Bump up the version in package.json
- version number explained:
- 1.0.0: major release with potentially breaking changes
- 1.0.0: new feature release
- 1.0.0: patch release
Git add and commit
git tag 1.1.0 (git tag 1.1.0-beta.0 if it's a beta version)
git push
git push --tags
npm publish (npm publish --tag beta if it's a beta version)
npm info lab-starwars-names
npm i lab-starwars-names@beta to install the beta version
npm i lab-starwars-names@1.1.0-beta.0 to install a specific version

Setting up unit testing with Mocha and Chai

Install mocha and chai

$ npm i -D mocha chai

all the source code at this point can be found at this commit

Update package.json

"scripts": {
  "test": "mocha src/index.test.js -w"
}

$ npm test

Automating releases with semantic-release

Install semantic-release-cli

$ npm i -g semantic-release-cli

travis.yml (the npm run test command will need to be added manually after the yml file generated) Note that the -w flag will cause travis CI build to fail, add another npm script "test:single": "mocha src/index.test.js" that drops the -w flag, then update travis.yml, replacing npm run test with npm run test-single

Committing a new feature with committizen

Automatically running tests before commits with ghooks

Install ghooks

$ npm i -D ghooks

Update package.json

"config": {
  "ghooks": {
    "pre-commit": "npm run test:single"
  }
}

Adding badges to README with shields.io

Adding ES6 support

all the source code at this point can be found at this commit

Install dependencies

$ npm i -D babel-cli rimraf # cross platform rm
$ npm i -D babel-preset-es2015 babel-preset-stage-2

Update package.json

"main": "dist/index.js",
"files": [ // what to include in the npm package
  "dist",
  "README.md"
],
"scripts": {
  "prebuild": "rimraf dist",
  "build": "babel --copy-files --out-dir dist --ignore *.test.js src"
},
"babel": { // configure babel
  "presets": ["es2015", "stage-2"]
}

Update .gitignore to ignore dist directory Adding ES6 support to tests as well

$ npm i -D babel-register # enable mocha ES6 support

"scripts": {
  "watch:test": "npm t -- -w",
  "test": "mocha src/index.test.js --compilers js:babel-register"
}

Add a browser build to an npm module

all the source code at this point can be found at this commit

Install webpack and the loaders

$ npm i -D webpack
$ npm i -D babel-loader json-loader

Add webpack.config.babel.js

import {join} from 'path'

const include = join(__dirname, 'src')

export default {
  entry: "./src/index",
  output: {
    path: join(__dirname, 'dist'),
    libraryTarget: 'umd',
    library: 'labStarwarsNames'
  },
  devtool: 'source-map',
  module: {
    loaders: [
      { test: /\.js$/, 'loader': 'babel-loader', include },
      { test: /\.json$/, 'loader': 'json-loader', include }
    ]
  }
};

Update build script

"scripts": {
  "build:main": "babel --copy-files --out-dir dist --ignore *.test.js src",
  "build:umd": "webpack --output-filename index.umd.js",
  "build:umd.min": "webpack --output-filename index.umd.min.js -p"
}

Install the npm-run-all to bundle 3 different builds into a single build

$ npm i -D npm-run-all

"scripts": {
  "build": "npm-run-all --parallel build:*",
  "build:main": "babel --copy-files --out-dir dist --ignore *.test.js src",
  "build:umd": "webpack --output-filename index.umd.js",
  "build:umd.min": "webpack --output-filename index.umd.min.js -p"
}

Getting the umd build via npm cdn

Once the package had been published, the umd build can be accessed via npm cdn! umd.js umd.min.js

genkio / blog