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:
Thank you for the
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
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 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?
- The Golden Rule: avoid coding wherever possible
- Upcoming sections
The Golden Rule: avoid coding wherever possible
Be optimally lazy. There are only two principles:
- 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:
- 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
This section covers general problems regardless of your development goals.
This sounds simple enough, but unfortunately the Node.js website makes you choose a version of Node.js to download.
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.
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.
Download and install these tools:
- Editor: Atom
- Atom packages/plug-ins:
- Package Installation script here
Packages➔ Search for
Settings➔ toggle the
Beautify On Saveoption for every language you want)
Ctrl/Cmd+Pin the editor to open the preview)
platformio-ide-terminal(terminal at bottom of editor)
Ctrl/Cmd+Shift+Min the editor to open the preview)
linter(A linter is a small program that checks code for stylistic or programming errors. Available linters )
highlight-selected(Double click on a word to highlight it throughout the open file.)
minimap(broad overview of code)
.tssupport for atom)
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)
- Atom packages/plug-ins:
- Version control: git
- Repository (repo) hosting: GitHub
- Git GUI: SourceTree
- API testing: Postman
- Socket testing: Socket.io tester
Set up a brand new project.
- Create a new repo on GitHub
- Choose Node under the gitignore settings when creating a repo
- Choose to create a README.md file
- Clone it to your computer using either a terminal command or SourceTree
- Set up your file and folder structure
- Open a terminal window in your repo folder (or use the Terminal button when you open the repo in SourceTree)
npm initin your terminal to create a
- 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
MITwhen prompted for a license name
atom .in your terminal to launch Atom in your project folder
File and folder structure
Set up a file and folder structure that lets you add more complexity later, such as build and test systems.
- Create one subfolder:
src: place all your source code here
- Create a file in the
Develop a coding style that lets you share your code without embarrassment.
A sloppy coding style reflects poorly on you.
Native modules and Windows
Fix errors related to
node-gyp when you try to install an npm package.
How to find alternatives:
- 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.
Do this if and only if you cannot find a suitable alternative npm package.
Follow the Windows installation instructions at the node-gyp README.
Read this if you are trying to build a web application.
Choose a technology stack (e.g. server framework, database, front-end framework, hosting platform).
This section covers problems commonly encountered with:
- serving mobile users for web applications
I am seeking contributors for this section.
This section covers problems commonly encountered with developing and distributing desktop applications.
I am seeking contributors for this section.
Package and run your Node.js app as a desktop application on any operating system (OS).
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.
This section covers problems commonly encountered with developing and publishing reusable packages.
Publish to NPM
Shows how to publish your own module to npm and then install anywhere
- 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
- 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
Update version numbers in a way that indicates how significantly the package has changed for its users
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
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:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- 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.
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:
- 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)
- 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
- Writing command line tools
- Publishing to NPM
- 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
- Message queues and async function execution
- Immediate user feedback for server requests
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.|
Thanks to the following for helping with ideas and edits
Copyright (c) 2016 Faraz Syed. This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License