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 ❤️ over the past two years. Hope this playbook still helps you get started fast with Node.js!
Node.js Playbook is an opinionated "get started" guide to developing with Node.js.
The playbook helps you in two ways:
🌐 How to get here: nodeplaybook.com
The playbook is a learning tool, and you must understand its limitations.
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.
Each solution was chosen after balancing:
Be optimally lazy. There are only two principles:
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:
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)
Set up a brand new project.
npm initin your terminal to create a
0.1.0(see also version numbering)
src(see also file and folder structure)
MITwhen prompted for a license name
atom .in your terminal to launch Atom in your project folder
Set up a file and folder structure that lets you add more complexity later, such as build and test systems.
src: place all your source code here
Develop a coding style that lets you share your code without embarrassment.
A sloppy coding style reflects poorly on you.
Fix errors related to
node-gyp when you try to install an npm package.
How to find alternatives:
Make sure that your chosen alternative is a suitable replacement. Look for:
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:
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.
Shows how to publish your own module to npm and then install anywhere
npm install <your module name>to check whether could be installed successful!
Update version numbers in a way that indicates how significantly the package has changed for its users
Use Semantic Versioning (a.k.a. semver).
npm version patch
npm version minor
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:
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