NPM Coding Style Guide: Best Practices and Conventions

This tutorial will explore the npm coding style, we will cover things like; line length, indentation, curly braces, semi colons, comma first, quotes, whitespaces, functions, callbacks and more coding conventions used by npm.

Description

The coding style of npm is not like the conventional coding styles that you may have come across. This coding style is not different just because npm wants to be different from everyone but because they want to reduce visual cluster and make debugging easier.

It should be noted that these conventions apply to npm's code and not the specific packages that you can download from the npm registry.

Line Length

It is recommended that you keep your lines of code shorter than 80 characters. You should break up long objects, lists, and other statements unto multiple lines.

Indentation

Two-spaces. It is better to use tabs, but they will look like hell in web browsers, also node uses 2 spaces, so maintain two-spaces. It is advisable that you configure your code editor appropriately.

Curly braces

Curly braces should belong on the same line as whatever necessitates them.

This is bad:

function ()
{```
While this is good:
```function () {```
you should only use a curly brace when a block has to wrap to the next line.
Bad:
```if (bar) { foo() }
while (bar)
  foo()```
Good:
```if (bar) foo()
while (bar) {
  foo()
}

Semicolons

You should only use semicolons for these situations such as:

• Inside a for(;;). This is required.
• In a null loop: while(something); ( a null loop requires a good reason for implementing them)
• case 'bar': doSomething(); break
• In front of a leading [ or ( at the start if the line. This will prevent the expression from being interpreted as a property access or function call respectively.

Here is an example to illustrate all these:

;(x || y).performAction()
;[a, b, c].forEach(performAction)
for (var i = 0; i < 10; i ++) {
  switch (state) {
    case 'begin': start(); continue
    case 'end': finish(); break
    default: throw new Error('unknown state')
  }
  end()
}

Comma First

This probably will be the hardest for you to accept. If you have a list of things that are separated by a comma, and the list wraps across multiple lines. You should put the comma at the start of the next line, directly below where the list starts. Then put the final token in the list on a line by itself. For instance:

var magicWords = [ 'lorem'
                 , 'ipsum'
                 , 'denim'
                 ]
  , spells = { 'fireball' : function () { setOnFire() }
             , 'water' : function () { putOut() }
             }
  , a = 'hail'
  , b = 'snow'
  , etc
  , anotherThing

Quotes

You should use single quotes for strings except to avoid escaping.

Bad:

var notOk = " this is just double quotes"

Good:

var ok = 'String containing "double" quotes'
var alsoOk = "String containing 'single' quotes or apostrophe"

Whitespace

You should put a single space in front of ( for anything apart from a function call. You should also use a single space wherever it makes things more readable.

Do not leave trailing whitespace at the end of lines. Do not indent empty lines. Finally, do not use more spaces than is needed.

Functions

You should use named functions. They will make stack traces a lot easier to read.

Callbacks, Sync/async Style

You need to use the asynchronous/non-blocking versions of things as much as possible. It might make more sense for npm to utilize the synchronous fs APIs, but this way, the fs and http and child process stuff will all use the same callback-passing methodology.

The callback has to always be the last argument in the list. Its first argument will be the Error or null.

Be very careful never to ever throw anything. It's worse than useless. You just need to send the error message back as the first argument to the callback.

Errors

You should always create a new Error object with your message. Do not just return a string message to the callback. Stack traces are handy.

Logging

npmlog utility is used for logging.

You should clean up logs when they are no longer helpful. particularly, it is not helpful to log the same object over and over again. Logs should report what is happening so that it's easier to track down where a fault occurs.

Please that you use the appropriate log levels.

Case, naming, etc.

Ensure that you use lowerCamelCase for multiword identifiers when they refer to objects, functions, methods, properties, or anything that is not specified in this section.

Make sure that you use UpperCamelCase for class names (things that you'd pass to "new").

You should use all-lower-hyphen-css-case for multiword filenames and config keys.

Ensure you use named functions. They will make stack traces easier to follow.

Make use of CAPS_SNAKE_CASE for constants, things that should never change and are rarely used.

Ensure you use a single uppercase letter for function names where the function would normally be anonymous, but has to call itself recursively. It will make it clear that it's a "throwaway" function.

null, undefined, false, 0

Boolean variables and functions always need to be either true or false. You should not set it to 0 unless it's supposed to be a number.

Whenever something is intentionally missing or removed, you should set it to null.

Never set things to undefined. You should reserve that value to mean "not yet set to anything."

It is forbidden to use Boolean objects.

Previous: Docker and private packages.
Next: Comprehensive Guide to npm Configuration Settings.