Skip to content
This repository has been archived by the owner on May 27, 2022. It is now read-only.

voorhoede/npm-style-guide

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
 
 
 
 
 
 

Repository files navigation

NPM Style Guide

Opinionated ​NPM Style Guide​ for teams by De Voorhoede.

Purpose

This guide provides a set of rules to better manage, test and build your NPM modules and project tasks runners. It should make them

  • easier for a new developer to pick up
  • reduce friction with different environment configurations
  • have a predictable api
  • easier to add new tasks

Table of Contents

Use nvm to manage node versions

Why?

With nvm you can have multiple different versions available and switch to the one that suits better your project.

How?

To install or update nvm, you can use the install script using cURL:

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash

For Windows check nvm for windows.

If everything goes well, you can now install a specific node version.

nvm install stable
nvm install vX.Y.Z
nvm alias default stable

It’s also easy when updating a newer version, copying your existing global modules.

nvm copy-packages <previous-version>

↑ back to Table of Contents

Configure your npm personal info

Why?

When creating a new package npm init your defaults will be already included on the scaffolding.

How?

npm config set init-author-name "{name}"
npm config set init-author-email "{email}"

Check npm config docs, for more info.

You can use cat ~/.npmrc to check your current definitions.

↑ back to Table of Contents

Use save exact option

Why?

By default, installing a package with the --save or --save-dev option, npm saves the package version with ^ prefix, meaning that will update minor versions if available. While this is a good idea as is, this makes it possible for different developers having different versions of the same package and making it harder to debug if there is inconsistency. Defining the save-exact option prevents this. More info npm config docs.

How?

npm config set save-exact

↑ back to Table of Contents

Avoid installing modules globally

NPM first tries globally installed modules before looking for local ones. Globally installed modules are shared between projects and might not match the required version for the project.

Why?

  • Locally installed modules are custom and specific for the project.
  • Locally installed modules are directly accessible via npm scripts.

How?

# recommended: install locally
npm install --save-dev grunt-cli grunt

and use in package.json:

"scripts": {
  "icons": "grunt grunticons"
}
# avoid: don't install modules globally
npm install -g grunt-cli grunt

More about npm scripts.

↑ back to Table of Contents

Write atomic tasks

Each task should be only responsible for one action.

Why?

  • Atomic tasks are easy to read and understand.
  • Atomic tasks are easy to reuse.

How?

Separate each step of the task to an individual task. For example a "generate icon" task can be split into atomic tasks like "clean directory", "optimize SVGs", "generate PNGs" and "generate data-uris for SVGs".

↑ back to Table of Contents

Use npm modules for system tasks

Why?

When you use system specific commands like rm -rf or &&, you are locking your tasks to your current operating system. If you want to make your scripts work everywhere think about Windows developers also.

How?

Use npm modules with node that mimic the same tasks but are system agnostic. Some examples:

  • create directory (mkdir / mkdir -p) -> mkdirp
  • remove files and directories (rm ...) -> rimraf
  • copy files (cp ...) -> ncp
  • run multiple tasks in sequence (... && ...) or in parallel (... & ...) -> npm-run-all
  • set environment variable (ENV_VAR = ...) -> cross-env

↑ back to Table of Contents

Document your script API

Why?

  • Documentation provides developers with a high level overview to the script, without the need to go through all its code. This makes a module more accessible and easier to use.

  • Documentation formalises the API.

How?

Document your script API in the project's README.md or CONTRIBUTING.md as those are the first places contributors will look. Describe what each task using a simple table:

`npm run ...` | Description
---|---
task | What it does as a plain human readable description.

An example:

npm run ... Description
build Compile, bundle and minify all CSS and JS files..
build:css Compile, autoprefix and minify all CSS files to dist/index.css.
build:js Compile, bundle and minify all JS files to dist/index.js.
start Starts a server on http://localhost:3000.
test Run all unit and end-to-end tests.

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •