hifaraz/node-playbook

Get started fast with Node.js

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:

If you want to ...	How to contribute
Ask for a recommended solution to a particular problem or goal	First, check the Upcoming sections. We may already be planning to work on it. If it isn't listed in the Upcoming sections, please either create a GitHub Issue or send a pull request to add it to the Upcoming sections.
Provide a solution to a problem or goal	That's great! Please create a GitHub issue to discuss the solution before creating a pull request. Please consider the criteria for accepting a solution.
Offer a better solution than one already in the Playbook.	Please create a GitHub Issue to discuss this. Consider whether it meets the criteria for accepting a solution. Because we are focused on finishing upcoming sections, we are only accepting improvements if they are vastly better than the current solution.
Translate the Playbook	That's great! Please join the discussion in our i18n GitHub Issue.

❤️ 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)

node-playbook's Issues

plan to separate the playbook into multi parts?

too many in README.md now, recommend create a dir and put contents into it, then make some links for better readability!

Windows & node-gyp

I just wanted to leave a comment on this.
It is true that installing node-gyp on a windows machine gives errors, but there is a solution.

With Windows 10 Anniversary update, users can enable Ubuntu's bash. Using that, you can install the package without any issue, and I'd recommend it to all people who use windows for developing.

Recommend React for both the front-end and mobile

I believe it makes sense to recommend React as the front-end JavaScript recommendation, as well as mobile.

First, with React, you get both standard React and React Native, which means you learn once, write anywhere. Once you know the JSX syntax and get comfortable with React your skills apply anywhere. This simplifies development and allows you to focus on features and functionality rather than language differences.

Second, with the recent advent of create-react-app and the stabilization of react-native-cli, creating React apps on both the web and mobile platforms is as simple as running through a quick wizard, fitting right into this playbook's paradigm of write as little code as possible and make as few technology decisions as possible.

I'm happy to put together a PR for this, but I wanted to get feedback before I submitted something.

How about CloudFlare for the free CDN option?

https://www.cloudflare.com/features-cdn/
https://www.cloudflare.com/dns/
https://www.cloudflare.com/plans/

They support custom domains and offer CDN and caching services all within their free tier.

Misc improvements

Add GitLab as VCS. Link all 3 to the sites. GitLab is cheapest w/ a lot of cool features (KanBan boards). GitHub is most well known, BitBucket has Atlassian integration, and is also cheaper than GitHub.
https://github.com/pricing
https://about.gitlab.com/pricing/
https://bitbucket.org/product/pricing

Add code to auto-install atom plugins eg apm install minimap # https://atom.io/packages/minimap. Add atom packages minimap, minimap-cursorline, linter, emmet, pigments, double-tag, IDK what else (if you so desire).

Is source tree really necessary? IDK as I've never used it before. But the source says only for Windows & Mac. I'd think you'd want to encourage devs to use a Linux OS, and learn Git.

Again, I think "Native modules and Windows" section's default solution should be to use Linux haha. A workaround via installing similar yet different NPM packages will lead to using outdated packages in the long run.

For hosting I would add in alternatives of Digital Ocean and Amazon web services. (alt: DO, AWS). You have some alternatives for VCS so I think it makes sense here.

Electron vs Cordova. I had never heard of Electron, after googling it seems like Cordova focuses mainly on mobile and Electron does desktop. I would remove Cross platform framework header, as I think it's confusing. Instead move Electron recommendation under Developing desktop applications.

Hybrid framework reference (mobile section). I've used plain Cordova in a past project, I'll check out what Iconic and PhoneGap contribute.

Consider StandardJS as an alternative to AirBNB

Less popular than AirBNB's guide, but a better idea:

Advantages:

• You can npm install --save-dev standard, then standard as part of your npm test to ensure code is written in a standard way.
• No bikeshedding! Bikeshedding is a real time-killer, endless discussions about what styles to adopt.
• No configuration. For the reasons above, configuration is actually prohibited! One style - no arguments.

Mobile Applications

I think the recommendation should be Ionic, not PhoneGap (proprietary) or vanilla Cordova (lacks some performance, no UI helper, Ionic has better API). I've personally used vanilla cordova, but Ionic is also open source and appears to be more recommended.

http://blog.ionic.io/what-is-cordova-phonegap/
https://github.com/jessemonroy650/top-phonegap-mistakes/blob/master/hybrid-frameworks.md

Crosswalk should also be included by default to new projects.

https://crosswalk-project.org/
http://blog.ionic.io/crosswalk-comes-to-ionic/

Terminal-plus package for Atom is inactive.

Terminal -plus package for Atom is not currently maintained. There is an issue with this package and newer Atom versions and Windows 10 (jeremyramin/terminal-plus#15). Guys from PlataformIO have forked and updated terminal-plus to work well (+ info jeremyramin/terminal-plus#223).

Native modules and Windows

Just use Linux? A workaround via installing similar yet different NPM packages will lead to using outdated, hard to find packages in the long run. If Linux is not possible, then I suppose it would be necessary

Ready to Provide a solution to Publishing to NPM

@HiFaraz is there other aspect should pay attention to except criteria for accepting a solution., step by step guide to publish to npm is my idea!

Publish to GitHub Pages

Stop calling AWS Lambda "Serverless"

I'm not quite sure what exactly to call it, but I think this would be a good place to start discouraging the use of the term "serverless." Serverless implies that your application somehow works without a server which makes no sense. AWS Lambda is still backed by running servers, as evidenced by the outage a few weeks ago where everyone running a "serverless" environment was affected.

Serverless isn't not using servers, it's using someone else's instead of building your own. There's value in that, but we should come up with a better term (Server as a Service?) to better describe the nature of the feature.

I know this isn't necessarily an issue that's specific to this repository, but if that section is aimed at teaching beginners about web infrastructure we should start by teaching people accurate terminology.

Cross Platform Framework

Electron vs Cordova. I had never heard of Electron, after googling it seems like Cordova focuses mainly on mobile and Electron does desktop. I would remove Cross platform framework header, as I think it's confusing. Instead move Electron recommendation under Developing desktop applications.

i18n support

I have a few friends who would be interested in this but they are not English speakers, are you planning on supporting multiple languages?

Consider HapiJS as an alternative to express

I switched from express to Hapi a long time ago when I was quite a novice node programmer, and I've not looked back. I think in terms of writing an comprehensible application, it's much better for beginners and experts alike.

My reasoning being:

1. Route validation is far too easy, and built in thanks to the Joi plugin
2. Declaring routes for an api is much more obvious, syntatically
3. Node applications should be developed in a modular way for ease of understanding, especially for somebody new to it. Hapi enourages everything to be done as plugins, which absolutely promotes and assists in this.
4. Hapi is battle tested with Walmart's black friday traffic. No problems here!
5. Hapi has plenty of tutorials on the actual website
6. A wealth of easy to understand tutorials exist on the Hapi site
7. Plenty of view rendering plugins are a one-line install
8. Hoek is built in and solves a lot of common js problems you encounter when parsing input (like reaching properties on objects without null)
9. Boom is built in which provides a one-liner solution for rendering client-parse-able error responses
10. Good is built in to save you having to look for a logging framework. This also gives you request.log for request-level-traceability of your logging, which is also useful for novices.

And if you're considering react, as I see in another PR, Hapi's isomorphic rendering of react is unbeatable.

Add giteye as gitgui for linux systems

This is the best gui client for linux http://www.collab.net/downloads/giteye

Translators welcome - i18n

Please leave a comment here if you'd like to maintain another language version of the playbook.

So far we have:

• Hungarian - https://github.com/HiFaraz/node-playbook-hu

Grunt vs Gulp vs NPM build scripts

I have no idea.

Atom package recommendations

Add code to auto-install atom plugins eg apm install minimap # https://atom.io/packages/minimap. Add atom packages minimap, minimap-cursorline, linter, emmet, pigments, double-tag, IDK what else (if you so desire).

Thoughts about referring to awesome-atom?

I suggest to at least include a reference to mehcode/awesome-atom in this section.

Thoughts in general about adding a "read more" link to some/all sections?

VCS recommendations

Add GitLab as VCS. Link all 3 to the sites. GitLab is cheapest w/ a lot of cool features (KanBan boards). GitHub is most well known, BitBucket has Atlassian integration, and is also cheaper than GitHub.
https://github.com/pricing
https://about.gitlab.com/pricing/
https://bitbucket.org/product/pricing

Is source tree really necessary? IDK as I've never used it before. But the source says only for Windows & Mac. I'd think you'd want to encourage devs to use a Linux OS, and learn Git.

Hosting

For hosting I would add in alternatives of Digital Ocean and Amazon web services. (alt: DO, AWS). You have some alternatives for VCS so I think it makes sense here.