Starwars-Names

This is just an example of how to write a javascript library configuring npm and creating a package json from egghead.io.

Create github repo

Create new repo on github and execute the following:

echo "# starwars-names" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin https://github.com/your-account/starwars-names.git
git push -u origin master

Configuring npm and creating a package.json

To configure npm do the following:

npm set init-author-name 'Your Name'
npm set init-author-email '[email protected]'
npm set init-author-url 'http://your-url.com'
npm set init-license 'MIT'
npm set save-exact true

check settings in .npmrc

Setup a npm-account and login via console:

npm adduser

following instructions.

Setup package.json

npm init -y

create an default package.json where you can add right content later.

Creating the library

• create src/index.js

var starWarsNames = require('./starwars-names.json');

module.exports = {
  all: starWarsNames,
  random
}

• move starwars-names.json to src/
• install npm module unique-random-array to appear in dependencies (--save)

npm i -S unique-random-array

• update src/index.js

var uniqueRandomArray = require('unique-random-array');
var starWarsNames = require('./starwars-names.json');

module.exports = {
  all: starWarsNames,
  random: uniqueRandomArray(starWarsNames)
}

• test it manually in console

node
> var lib = require('./src/index.js')
> lib.all // logs all names
> lib.random // logs random name

Create .gitignore

*~
.DS_Store
.idea/
node_module

Publish library to npm

run

npm publish

and check with

npm info starwars-names

Releasing a version to github

add tag

git tag 1.0.0
git push --tags

check on github

Releasing a new version to npm

• add a new name to starwars-names.json

"Sabine Wren"

• update version
  • first number major version change
  • second number minor release with new features
  • a patch release like bug-fixes
• increase second number to 1

"version": "1.1.0"

• update to git and npm

git add -A
git commit -m "your commit message"
git tag 1.1.0
git push
git push --tags
npm publish

• check with

npm info starwars-names-test-seebaermichi

Releasing a beta version

• just increase version as needed and add -beta.0 to version number
• update everything to git and npm

git add -A
git commit -m "commit message"
git tag 1.1.0-beta.0
git push
git push --tags
npm publish --tag beta

• check

npm info

• to install not beta version

npm install starwars-names-test-seebaermichi

• to install latest beta version

npm install starwars-names-test-seebaermichi@beta

or

npm install [email protected]

• if beta version is ready for final release just remove beta from version number and publish it as a normal version

Add Tests

• install packages

npm i -D mocha chai

• add src/index.test.js just to test if test is running

var expect = require('chai').expect;
var starWars = require('./index');

describe('starwars-names', function () {
  it('should work!', function () {
    expect(true).to.be.true;
  })
});

• update test-script in packages.json

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

• run test in console

npm test

Unit testing

• we write a test for starWars.all and starWars.random()
• for all replace it('should work!') by:

describe('all', function () {
  it('should be an array of strings', function () {
    expect(starWars.all).to.satisfy(isArrayOfStrings);
    
    function isArrayOfStrings (array) {
      return array.every(function (item) {
        return typeof item === 'string';
      });
    }
  });
});

• and run

npm test

• cross-check by replace ...to.satisfy(... with ...to.not.satisfy(... - test should fail
• add further test to src/index.test.js

it('should contain `Luke Skywalker`', function () {
  expect(starWars.all).to.include('Luke Skywalker');
});

• add test for starWars.random()

describe('random', function () {
  it('should return a random item from the starWars.all', function () {
    var randomItem = starWars.random();
    expect(starWars.all).to.include(randomItem);
  });
});

Automate Releasing

setup semantic-release-cli

• automate with semantic-release-cli

npm i -g semantic-release-cli

• setup semantic-release-cli

semantic-release-cli setup

• use everywhere the default but choose Travis CI and Single Node.js verion
• find some updates in package.json, e.g. remove verion, new script command semantic-release
• restore version in package.json to

"verion": "0.0.0-semantically-released"

to prevent warnings

• semantic-release runs automatically in accordance to settings in .travis.yml
• find a new file .travis.yml
• add following line before after_success: in .travix.yml

script:
  - npm run test

this makes sure package is only released if tests pass

Writing conventional commits

• use commitizen and cz-conventional-changelog

npm i -D commitizen cz-conventional-changelog

• adjust package.json to add new script

"scripts": {
  ...
  "commit": "git-cz",
  ...
}
...
"csConfig": {
  "path": "node_modules/cz-conventional-changelog"
}

• create new issue 'simplify releases' in github as an example
• commit changes with conventional commit

npm run commit

follow instructions

Add new feature

• tdd so add following test for random to src/index.test.js

it('should return an array of random if passed a number', function () {
  var randomItems = starWars.random(3);
  expect(randomItems).to.have.length(3);
  randomItems.forEach(function (item) {
    expect(starWars.all).to.include(item);
  });
});

• test fails as expected
• add feature to src/index.js

var uniqueRandomArray = require('unique-random-array');
var starWarsNames = require('./starwars-names.json');
var getRandomItem = uniqueRandomArray(starWarsNames);

module.exports = {
  all: starWarsNames,
  random: random
};

function random (number) {
  if (number === undefined) {
    return getRandomItem();
  } else {
    var randomItems = [];
    for (var i = 0; i < number; i++) {
      randomItems.push(getRandomItem());
    }
    return randomItems;
  }
}

• update package

git add -A
npm run commit
? Select the type...: feat
? Denote the scopt:
random
? Write a short...
Add ability to get an array of starwars names
? Provide a longer...
If you pass a number to the random function, you will receive an array with that number of random items.
? List any breaking...
closes #2