Hi! This guide is two years old. It's still pretty good though.

I'd love some help in modernizing this please. We still need a solid playbook for the Node.js ecosystem. If you've benefited from this please consider contributing back - there's a big todo list! File an issue if you can help.

Meanwhile I have a few significant new/changed recommendations:

• Frontend: React, with Create React App
• Editor: Visual Studio Code
• Packaging and deploying: Docker

Thank you for the ❤️ over the past two years. Hope this playbook still helps you get started fast with Node.js!

Faraz Syed

Node.js Playbook

Node.js Playbook is an opinionated "get started" guide to developing with Node.js.

The playbook helps you in two ways:

• solving problems: if you have a specific need, it gives you a solution that works for most people
• discovering new ideas: if you just browse, you will learn new things that can help your project

🌐 How to get here: nodeplaybook.com

Click here to jump to the table of contents

Who this is for

• Beginners who just want to get a project started without too much hassle
• Experienced programmers who want a "get started" guide to unfamiliar parts of the Node.js ecosystem

How to use this playbook

The playbook is a learning tool, and you must understand its limitations.

• Read documentation and tutorials to implement any solution. The playbook does not replace them
• This does not teach you how to program
• This does not teach you JavaScript
• This is not the only way to develop with Node.js. Use this playbook to get started, and keep learning about other ways to solve do things in Node.js
• This is not the best way to develop with Node.js. It is a way that is good enough to get started without a lot of learning overhead. Once your project grows in complexity you are expected to find solutions that are a better fit for your needs
• Not all advice is specific to Node.js

Do not use this playbook as your only source of learning. The playbook only gives you the most broadly applicable solution. As your needs grow you should explore other solutions. This is not the be all and end all of Node.js development. It should only be a part of your learning experience and exploration, not the whole.

How solutions were chosen

Each solution was chosen after balancing:

• is it stable? (look for a version 1)
• is it actively maintained?
• does it have good documentation?
• is it popular? (so that you can find lots of tutorials and a support community)
• is it free and open source? (as much as possible, except for hosting and domains)
• is it easy to learn?
• is it practical to use daily?
• does it work well with the rest of the playbook?

Contents

1. The Golden Rule: avoid coding wherever possible
2. General
   1. Installing Node.js
   2. Development environment
   3. Workflow
   4. File and folder structure
   5. Coding style
   6. Native modules and Windows
3. Web
   1. Technology stack
4. Mobile
5. Desktop
   1. Multi-OS framework
6. Packages
   1. Version numbering
   2. Publish to NPM
7. Upcoming sections
8. Contributing
   1. Acknowledgements
9. License

The Golden Rule: avoid coding wherever possible

Be optimally lazy. There are only two principles:

1. The fastest way to finish a task is to do nothing

• Ask yourself if you can live without it
• Less code means less bugs
• See also:
  • You aren't gonna need it (YAGNI)
  • Customer development
  • Minimum viable product (MVP)

1. The second fastest way to finish a task is to get someone else to do it

• For example, this playbook is an example of using someone else's work to get ahead
• Use Node.js core API if you can get away with it
• Use pre-built pieces of code, such as npm packages
  • Make sure you use high quality dependencies

(back to top)

General

This section covers general problems regardless of your development goals.

Installing Node.js

Goal

Install Node.js.

This sounds simple enough, but unfortunately the Node.js website makes you choose a version of Node.js to download.

Solution

Choose Node.js v6. It is in long term support (LTS), which means that further updates are mostly limited to bug fixes and security updates. This gives you peace of mind against major new features popping up in Node.js while you build your app.

Version 6 will stay in LTS for 18 months, and will switch to maintenance mode in April, 2018.

(back to top)

Development environment

Goal

Set up a development environment (e.g. editors, git GUIs, terminals, FTP clients) that gets you started and lets you grow according to you needs.

Solution

Download and install these tools:

• Editor: Atom
  • Atom packages/plug-ins:
    • Package Installation script here
    • atom-beautify ( Ctrl/Cmd+comma ➔ Packages ➔ Search for atom-beautify ➔ Settings ➔ toggle the Beautify On Save option for every language you want)
    • atom-html-preview (press Ctrl/Cmd+P in the editor to open the preview)
    • fold-lines
    • platformio-ide-terminal (terminal at bottom of editor)
    • markdown-preview (press Ctrl/Cmd+Shift+M in the editor to open the preview)
    • linter (A linter is a small program that checks code for stylistic or programming errors. Available linters )
    • linter-jshint (JavaScript linter)
    • highlight-selected (Double click on a word to highlight it throughout the open file.)
    • minimap (broad overview of code)
    • minimap-cursorline
    • atom-typescript (.ts support for atom)
    • autoclose-html
    • double-tag (edit HTML open and close tags simultaneously)
    • color-picker (highlight a color, right click, choose color-picker. Can view & edit colors visually)
    • package-sync (save atom packages across computers with a config file)
• Version control: git
• Repository (repo) hosting: GitHub
  • free private repos for students
• Git GUI: SourceTree
• API testing: Postman
• Socket testing: Socket.io tester

(back to top)

Workflow

Goal

Set up a brand new project.

Solution

1. Create a new repo on GitHub

• Choose Node under the gitignore settings when creating a repo
• Choose to create a README.md file

1. Clone it to your computer using either a terminal command or SourceTree
2. Set up your file and folder structure
3. Open a terminal window in your repo folder (or use the Terminal button when you open the repo in SourceTree)
4. Run npm init in your terminal to create a package.json file

• Set your initial version to 0.1.0 (see also version numbering)
• Set the entry point to src (see also file and folder structure)
• For open source projects choose an MIT license by typing MIT when prompted for a license name

1. Run atom . in your terminal to launch Atom in your project folder

(back to top)

File and folder structure

Goal

Set up a file and folder structure that lets you add more complexity later, such as build and test systems.

Solution

1. Create one subfolder:
2. src: place all your source code here
3. Create a file in the src sub-folder called index.js

(back to top)

Coding style

Goal

Develop a coding style that lets you share your code without embarrassment.

A sloppy coding style reflects poorly on you.

Solution

Follow Airbnb's Javascript Style Guide

(back to top)

Native modules and Windows

Goal

Fix errors related to node-gyp when you try to install an npm package.

The problem is due to non-JavaScript code in the package, which npm tries to build on your computer. You will get errors unless you have the build environment installed.

Recommended solution

Find another npm package that does the job in pure JavaScript. For example, bcryptjs is a drop-in replacement for the popular bcrypt module.

How to find alternatives:

• if the repo is hosted on GitHub or a similar platform, search the Issues for anyone mentioning Windows or node-gyp. It is likely someone in the thread has linked to a pure JavaScript replacement
• search online

Make sure that your chosen alternative is a suitable replacement. Look for:

• recently active contributors
• good documentation
• number of downloads

This is the simplest solution as it eliminates the problem rather than trying to accommodate it. The speed advantage from the native module will not be missed until later in your development cycle.

Alternative solution

Do this if and only if you cannot find a suitable alternative npm package.

Follow the Windows installation instructions at the node-gyp README.

(back to top)

Web

Read this if you are trying to build a web application.

Technology stack

Goal

Choose a technology stack (e.g. server framework, database, front-end framework, hosting platform).

Solution

• Back-end:
  • Hosting: Heroku (choose the "free dyno" option)
  • Server framework: express
  • Sockets: socket.io
  • Database: PostgreSQL (host it on Heroku with the free option)
  • Object-relational mapping: Sequelize
• Front-end
  • Domain: Namecheap
  • Hosting: CloudFlare
  • JavaScript: React
    • Use react-slingshot as a template. It sets up a project structure, an example app, and Redux as a state management system
  • Styling: Bootstrap

(back to top)

Mobile

This section covers problems commonly encountered with:

• developing and distributing native mobile applications in JavaScript
• serving mobile users for web applications

I am seeking contributors for this section.

(back to top)

Desktop

This section covers problems commonly encountered with developing and distributing desktop applications.

I am seeking contributors for this section.

Multi-OS framework

Goal

Package and run your Node.js app as a desktop application on any operating system (OS).

Solution

Use Electron. It is now considered stable as version 1 was released on May 11, 2016. It is backed by the makers of GitHub and Atom, and has a strong community. Electron apps build and run on Mac, Windows, and Linux.

(back to top)

Packages

This section covers problems commonly encountered with developing and publishing reusable packages.

Publish to NPM

Goal

Shows how to publish your own module to npm and then install anywhere

Solution

• Module uniqueness, visit npmjs to insure your named module is the unique
• Sign up account, by now, if no npmjs account, just sign up one which would be used to publish your module
• First publish, enter your module dir, just type npm publish
• Check publish, now, you have published your module, change to any other place, type npm install <your module name> to check whether could be installed successful!
• Publish again, it's necessary to up module version by Version numbering when you update the module and wish to publish again

(back to top)

Version numbering

Goal

Update version numbers in a way that indicates how significantly the package has changed for its users

Solution

Use Semantic Versioning (a.k.a. semver).

• Increment your patch (0.0.x) version with npm version patch
• Increment your minor (0.x.0) version with npm version minor
• Increment your major (x.0.0) version with npm version major

Using npm version will give you automatic package.json version updates, and will also create a git tag for you, that you can simply push with npm push --tags.

Here are the most important bits about semver:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

How should I deal with revisions in the 0.y.z initial development phase?

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

(back to top)

Upcoming sections

We'd like your help to make the Playbook more useful! Here are some sections that we'd love to receive a pull request on:

• General
  • Understanding event driven programming
  • Clustering (solution: throng)
  • Password hashing (solution: bcrypt)
  • Saving exact and secure dependency versions (solution: --save-exact, --secure, and .npmrc)
  • Good documentation / READMEs
  • Debug logging (solution: debug)
  • Event emitter (solution: eventemitter3)
  • Testing
  • User analytics and app monitoring
  • Other analytics: keen.io, google analytics and kissmetrics, and key metrics
  • Promises and callbacks, async code execution (maybe asyncawait too)
  • Error handling: callback convention, Promise.catch, try/catch for sync code
• Packages
  • Writing command line tools
  • Publishing to NPM
• Web
  • Creating a REST API server (solution: Swagger)
  • Deploying serverless (solution: serverless and AWS Lambda)
  • IaaS vs PaaS vs BaaS vs FaaS/serverless
  • Application architecture (solution: single page apps with a back-end API server)
  • Handling server overload (solution: toobusy)
  • Rate limiting and prevent brute force logins
  • Authentication (solution: jsonwebtoken)
  • Don't run your server on port 80 or 443, use a reverse proxy
  • Security
  • SSL
  • Message queues and async function execution
• Mobile
  • Immediate user feedback for server requests

(back to top)

Contributing

Contributions are welcome! Here's how you can help:

❤️ Acknowledgements

Thanks to the following for helping with ideas and edits

• aem
• antony
• Calinou
• dodekeract
• helloworld
• houjunchen
• JTronLabs
• krokofant
• mateoKaradza
• Morrisai
• necenzurat
• NicoPennec
• partounian
• talkahe
• wli
• xxdavid

(back to top)

License

Faraz Syed, 2016

Copyright (c) 2016 Faraz Syed. This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

(back to top)