README

vigour-boilerplate-module

A boilerplate of how to do modules

prerequisite
code
directory
tests
browser
server
modules
configuration
versioning
naming
installation
committing
publishing
readme

Prerequisite

Before you start be sure you have knowledge about

Code

As a rule of thumb your js should run in the browser and nodejs if possible, universal javascript. Aan exception would be for example, a c++ websocket server, this will not run in the browser!

Use es6 everywhere, always add a browserify transform using babel in your package.json. Except in the rare case where you're code cant run in the browser

"browserify": {
  "transform": [
    [
      "babelify",
      {
        "presets": [
          "es2015"
        ]
      }
    ]
  ]
}

When there is a difference between the browser and node use the browserify-browser field. /index.js is always the node-js file and /browser.js is the exception

"browser": {
  "./lib/something/index.js": "./lib/something/browser.js"
}

requirements

Use val as a word vs value
Always add use strict on top of your js files
When using promises make sure you catch errors!
When using generators make sure they run in the browser there is a util in vigour-util/regenerator
Use camelCase for variable names or properties (dont use something_else for example)
When using es7 make sure it works in node as well (by babelifying your code)

recommendations

Try to create small concise functions preferbly split up into many files
Use streams as much as possible when working in node (chunk based operation), to learn about streams check stream-adventure
When using vigour-base use inject with plain objects
Don't overcomlicate things with reusability, as a rule of thumb when something is done 3 times make something for it but not before

Tests

Create tests using

tap + tape, read this article for why tap.
precommit hook, helps with avoiding broken commits
browserstack
coveralls.io, when making a private module make sure to add a .coveralls.yml file
travis-ci
ducktape, a tool to test for common gotchas

In test if tests are reusable use a fn.js file wrapping the tests in a function

When using browserstack you need to set the environment vars BROWSERSTACK_USERNAME=${username} and BROWSERSTACK_KEY=${key}. Set these both locally and in your projects Travis settings.

For now you need to set NOW_TOKEN environment variable in Travis

When creating ui components try to use tests as your go to place to develop the component, run npm run watch-browser as defined in the scripts field of this module, same goes for the node.js but then use npm run watch
Enable your repo in travis by going to the pubic-profile for public modules and the private profile for private modules, then click the sync button and check the box for your repo
Set enviroment variables in travis in the repo settings
Enable coveralls.io by going to add new repo
Test as if you're working against a blackbox, you're tests need to do the same as users of modules don't tests internals test api with results (input - output), this allows you to refactor code many times and does not get you lost with too many tests
Do not tests things that are not part of your module e.g module a uses module b, do not test the funcionality of module b, do this in module b. This keeps tests concise and more valuable
Coverage is an indicator of normal tests as a rule of thumb when you have 90% coverage it shows that there are some tests. Beware, coverage does not mean that your tests are any good!
When developing start makeing unit tests, this is your spec from there you can start building the app code, see tests as the tool you develop with, this pattern is called TDD
Use npm run watch (located in the script folder) for fast development in node
Use npm run watch-browser to develop for the browser
When you have a server, do deploys trough travis by now after tests pass

Browser

List of supported browsers

Browsers should be able to run allmost all code, universal modules using browserify

Use feature detection in browsers
Make sure to test your module in multiple browsers, browserstack tests are very helpfull for this

css

Css4 with postcssify a transform for cssnext for browserify

"browserify": {
  "transform": [
    "postcssify": "^2.0.0"
  ]
}

'use strict'
require('./style.css')

In order to run this in node wihtout crashes there is an option to use vigour-util/require

At the start of your script add

require('vigour-util/require')()

Server

To start a server use npm start with no arguments To launch a server for testing puposes you can use now, they map port 80 to https by default.

Add your start script in a bin folder bin/server.js, this way you ensure that your module is allways usable programaticly
Do not add too many arguments to your start script, in general having one argument that is the port should be enough for development
Prefer errors over logs, throw Errors. In most cases where you usevigour-state the whole state will be stored in a database, this means every error is reproducable by replaying the history
Dont add too many dev-tools to your server, custom cli tools, too many fancy colorts in the console
For notifications make a slack channel for your service (e.g. service crashed, new version launched)
If you want a server that has to be redeployed on push (continous delivery), redploy your service from travis-ci after tests pass using now, this can be done on the same location as publishing your module

Modules

Always use specific modules e.g. lodash.merge vs lodash When you find a module make sure it works in node 6.3, and does not add too much code in the browser Prefer plain simple javascript, micro modules are ok as long as they do 1 thing simply, try to avoid adding too many large modules since it will bloat your code

blacklist

momment-js, to large for the client can be replaced with new Date() for most usecases
async don't need this , use es7 async functions with await
express use plain old http
hyperquest use plain old http
request use plain old http
All modules that "help" with logging for the server

prefered

uWebsocket over ws or websocket (uWebsocket is by far the fastest)
vigour-ua for ua sniffing/device info (its a small module ~1kb)

Configuration

Code over configuration -- try to add configuration variables in the package.json file In general try to keep configuration simple and in plain json files

For secrets like api keys, use environment variables
For determining environments use enviroment variables

Use envivfy to expose environment variables in your module in the browser

"browserify": {
  "transform": [
    "envivy"
  ]
}

Versioning

Use semver all the way this means

x.0.0 major api changes, or everytime changes break backwards compatibility
0.x.0 minor for added features
0.0.x patch for internal changes or bug fixes

always use the carret ^2.0.0 for dependencies, this updates minor and patch version automaticly

Naming

Repo Naming Conventions

Try to be broing but concise with names play-state-content

play, the product the module is part of
state, the subtopic (state)
content, the specific funcitonality

Extensions of modules always folow the same pattern e.g. blend-state-content-brightcove extends or replaces play-state-content This will keep reasoning about behaviours of modules simple for everyone

Installation

Modules should always be installable using npm i or npm i --production (wihtout dev dependencies)

Commiting

Git Workflow Guidelines

Commit to feature branches, there is no develop branch only master and feature, use pull requests even to yourself to merge features into master. Similair model as git flow, minus the develop branch. Reason to remove a devleop branch is to get less version disparity

Publishing

Publishing of modules has to be done trough travis-ci, make sure you setup an npm api-key in travis-ci as an enviroment variable so it can publish.

npm version patch, npm version minor, npm version major

Then pushing to github by doing git push --tags

When you push a major version be sure to edit the release notes in github

Readme

Follow the formatting in this readme.md Add Badges, coveralls, travis, npm and standard

Add a usage field in bold, like this

Usage

const somemodule = require('somemodule')
// initialize the module
const something = somemodule()

// do something
something.do() // → 'doing somehting'

Try to keep text to a minimum, code is usualy the best documentation

Code examples

Use the unicode arrow → to describe return values

const myfunction = require('myfunction')
myfunction() // → 'hello'

Property options

:key this is a property
:reset this is also a property
:val and another one

Make sure after you publish your module to npm that the readme and description in npm does not look bad

vigour-boilerplate-module

Usage no npm install needed!

README

vigour-boilerplate-module

Prerequisite

Code

Directory

Tests

Browser

Server

Modules

Configuration

Versioning

Naming

Installation

Commiting

Publishing

Readme