This is an opinionated "get started" guide to developing with Node.js.
Click here to jump to the table of contents
- Beginners who just want to get a project started without too much hassle
- Veterans who want a "get started" guide to unfamiliar parts of the Node.js ecosystem
You waste time by:
- discovering/researching basic aspects of Node.js development, and
- choosing from amongst several tool options that do the same job
Follow this playbook. It recommends basic choices that let you focus on writing code instead of setting things up.
- This does not teach you JavaScript
- This is not the only way to develop with Node.js. Use this playbook to get started, then use other choices when applicable
- 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
- This does not replace the need to read documentation
- Not all advice is specific to Node.js
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
- General problems
- Node.js version
- Development environment
- Workflow
- File and folder structure
- Coding style
- Native modules and Windows
- Developing for the web
- Technology stack
- Developing a package
- Version numbering
- Developing mobile applications
- Developing desktop applications
- Cross platform framework
- Upcoming sections
- Contributing
- Contributors
- License
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 your dependencies are of high quality
This section covers general problems regardless of your development goals.
Many versions are listed on the Node.js website. Choosing a Node.js version wastes time.
Choose Node.js v6. It will enter long term support (LTS) on October 1, 2016, after which it will stay in LTS for 18 months. This gives you peace of mind against major new features popping up in Node.js while you build your app.
Choosing a development environment (e.g. editors, git GUIs, terminals, FTP clients) wastes time. No tool is 10 times better than another. You need a set of tools that get you started and let you grow according to you needs.
Download and install these tools:
- Editor: Atom
- Atom packages/plug-ins:
- Package Installation script here
- atom-beautify (
Ctrl/Cmd+comma
➔Packages
➔ Search foratom-beautify
➔Settings
➔ toggle theBeautify On Save
option for every language you want) - atom-html-preview (press
Ctrl+P
in the editor to open the preview) - fold-lines
- terminal-plus (terminal at bottom of editor)
- markdown-preview (press
Ctrl+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)
- Atom packages/plug-ins:
- Version control: git
- Repository (repo) hosting: GitHub
- Git GUI: SourceTree (why: you can upload/push much faster and clone repos from GitHub and BitBucket)
- API testing: Postman
- Socket testing: Socket.io tester
Thinking about how to set up a new project wastes time.
- Create a new repo on either GitHub or BitBucket
- Choose Node under the gitignore settings when creating a repo
- Choose to create a README.md
- Clone it to your computer with either a terminal command or with 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)
- Run
npm init
in your terminal to create apackage.json
file
- Set your initial version to 0.1.0 (see also version numbering)
- If this is an open source project then choose an MIT license by typing
MIT
when prompted for a license name
- Run
atom ./
in your terminal to launch Atom in your project folder
Thinking about how to set up your project file and folder structure wastes time.
- Create three subfolders:
source
: place all your source code heretest
: place all testing code herebuild
(optional): use this as a destination folder if/when you implement a build system (something that converts your source code to another form)- Create a file in the
source
sub-folder calledindex.js
Fretting over coding style wastes time, and a sloppy coding style reflects poorly on you. You need a coding style that looks decent and is easy to follow.
Follow Airbnb's Javascript Style Guide
Some npm packages do not install on Windows because they contain non-JavaScript code. You will see errors related to node-gyp
when you try to install them.
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.
Do this if and only if you cannot find a suitable alternative npm package.
Follow the Windows installation instructions at the node-gyp README.
I never got this to work despite many tries.
This section covers problems commonly encountered with developing, deploying, and distributing web applications.
Choosing a technology stack (e.g. server framework, database, front-end framework, hosting platform) wastes time. Every stack is different and affects your project, however this is mostly a matter of style. Every stack will do the job.
- Back-end:
- Front-end
- Domain: Namecheap (affiliate link) [non-affiliate link]
- Hosting: Namecheap (affiliate link) [non-affiliate link]
- (seeking free CDN suggestions that support custom domains)
- JavaScript: React, using
react-slingshot
as a template for your project.react-slingshot
will set you up with a project structure, an example app, and Redux as a state management system - Styling: Bootstrap
This section covers problems commonly encountered with developing and publishing reusable packages.
Deciding on a version number scheme wastes time. Using a non-standard scheme confuses anyone using your package.
Use Semantic Versioning (a.k.a. semver). Here are the most important bits to get started:
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.
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.
This section covers problems commonly encountered with developing and distributing desktop applications.
I am seeking contributors for this section.
Deciding which cross platform framework to use is a waste of time.
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.
- General problems
- 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
- npm publish scripts that update version number for you
- promises and callbacks
- error handling
- Developing for the web
- Creating a REST API server (solution: Swagger)
- Deploying serverless (solution: serverless and AWS Lambda
- 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
- security
- ssl
- message queues and async function execution
- Developing mobile applications
- immediate user feedback for server requests
Contributions are welcome through GitHub Issues! Please contribute by:
- asking for recommended solutions to your favorite problem
- offering recommended solutions to a problem in Upcoming sections or in a GitHub Issue (please note the criteria for recommended solutions)
Thanks to the following for helping with ideas and edits
MIT License
Copyright (c) 2016 Faraz Syed
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.