W3C ∕ Node.js best practices and recommended tools

W3C logo          Node.js logo

Adherence to these guidelines is a prerequisite before moving a service from W3C Labs to production space (where it will be maintained by the Systems Team).

Contribute to this guide on GitHub.

Package manager 🔗

We use npm. Some of us have evaluated Yarn, but we are not convinced it's a better alternative at the moment.

Code conventions 🔗

Refer to “technical decisions” in the Design repository, § 4 “JS”. This is a work-in-progress based on personal experience and team feedback.

Security 🔗

We use npm audit to watch vulnerabilities in packages.

See eg how we use it in Echidna. We have devised a mechanism to keep track of known vulnerabilities (exceptions); see the file known-vulns.txt.

Until npm audit is capable of alerting of outdated packages too, sometimes we use npm-check in our scripts to check if there are outdated versions of packages.

Linting🔗

We lint our code using eslint with eslint-config-airbnb-base code style, see an example of usage in spec-generator, and the eslint config file we maintain.

The package eslint-plugin-node is also used, to provide a baseline of common rules (which we modify slightly via config).

We use prettier as code formatter, see sample config file for spec-generator.

Code coverage 🔗

We use packages istanbul and coveralls to measure code coverage.

See eg how we use it in Echidna, and the config file we maintain.

The (free) service Coveralls produces nice reports of code coverage and changes in it.

Dependency management 🔗

The (free) service Greenkeeper watches all npm packages that our application uses, and submits handy PRs every time there are updates. Set it up in the organisation configuration pages, under Installed GitHub apps (it should be given access strictly to the Node.js projects that need it).

Testing 🔗

We use mocha. Except for smaller test suites or in simpler projects, we usually pair it with the assertion library chai.

Suggested config file (typically under test/).

For testing on the browser, testharness.js may be useful, too (documentation, tutorial) — but note that it still needs to be properly packaged and available through npm.

Transpilers and module bundlers 🔗

We have used Babel in a couple of projects (npm: babelify), and recommend it when early-adopting new ES features.

We have used Browserify in at least one project (npm: browserify) to pack server-side JS for usage on the browser. We have not evaluated webpack yet (but we should at some point).

Front-end frameworks 🔗

Lately we have used mainly React, and that is the one we would recommend in general.

For some small tools or pages we have also used Angular (although way back when it was AngularJS) and we also liked it. And some of us have also experimented with (and liked) Vue.js.

Documentation 🔗

We use jsdoc with the style minami.

See an example of usage in Eunomia, and the config file we use.

Other recommended packages 🔗

The following is a list of miscellaneous npm packages that are battle-tested and that we recommend (apart from the ones already mentioned in sections above). It's often the case that there are several npm packages to achieve the same goal, so it's convenient for us to converge on a more or less “standard” suite of packages.

Also, make sure you check out our own (W3C's) npm packages on npmjs.com.

Additional notes and links 🔗