└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Hi! This guide is two years old. It's still pretty good though. 2 | 3 | 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](#upcoming-sections)! File an issue if you can help. 4 | 5 | Meanwhile I have a few significant new/changed recommendations: 6 | 7 | - Frontend: [React](https://reactjs.org/), with [Create React App](https://github.com/facebook/create-react-app) 8 | - Editor: [Visual Studio Code](https://code.visualstudio.com/) 9 | - Packaging and deploying: [Docker](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) 10 | 11 | Thank you for the :heart: over the past two years. Hope this playbook still helps you get started fast with Node.js! 12 | 13 | *[Faraz Syed](https://github.com/HiFaraz)* 14 | 15 | --- 16 | 17 | [![node-playbook banner](http://i.imgur.com/C1yh7Wj.png)](http://nodeplaybook.com) 18 | 19 | # Node.js Playbook 20 | 21 | Node.js Playbook is an opinionated "get started" guide to developing with Node.js. 22 | 23 | The playbook helps you in two ways: 24 | * **solving problems:** if you have a specific need, it gives you a solution that works for most people 25 | * **discovering new ideas**: if you just browse, you will learn new things that can help your project 26 | 27 | :globe_with_meridians: How to get here: [nodeplaybook.com](http://nodeplaybook.com) 28 | 29 | [Click here to jump to the table of contents](#contents) 30 | 31 | ### Who this is for 32 | 33 | * **Beginners** who just want to get a project started without too much hassle 34 | * **Experienced programmers** who want a "get started" guide to unfamiliar parts of the Node.js ecosystem 35 | 36 | ### How to use this playbook 37 | 38 | The playbook is a learning tool, and you must understand its limitations. 39 | 40 | * Read documentation and tutorials to implement any solution. The playbook does not replace them 41 | * This does not teach you how to program 42 | * This does not teach you JavaScript 43 | * 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 44 | * 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 45 | * Not all advice is specific to Node.js 46 | 47 | **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. 48 | 49 | ### How solutions were chosen 50 | 51 | Each solution was chosen after balancing: 52 | 53 | * is it stable? (look for a version 1) 54 | * is it actively maintained? 55 | * does it have good documentation? 56 | * is it popular? (so that you can find lots of tutorials and a support community) 57 | * is it free and open source? (as much as possible, except for hosting and domains) 58 | * is it easy to learn? 59 | * is it practical to use daily? 60 | * does it work well with the rest of the playbook? 61 | 62 | ## Contents 63 | 64 | 1. [The Golden Rule: avoid coding wherever possible](#the-golden-rule-avoid-coding-wherever-possible) 65 | 1. [General](#general) 66 | 1. [Installing Node.js](#installing-nodejs) 67 | 1. [Development environment](#development-environment) 68 | 1. [Workflow](#workflow) 69 | 1. [File and folder structure](#file-and-folder-structure) 70 | 1. [Coding style](#coding-style) 71 | 1. [Native modules and Windows](#native-modules-and-windows) 72 | 1. [Web](#web) 73 | 1. [Technology stack](#technology-stack) 74 | 1. [Mobile](#mobile) 75 | 1. [Desktop](#desktop) 76 | 1. [Multi-OS framework](#multi-os-framework) 77 | 1. [Packages](#packages) 78 | 1. [Version numbering](#version-numbering) 79 | 1. [Publish to NPM](#publish-to-npm) 80 | 1. [Upcoming sections](#upcoming-sections) 81 | 1. [Contributing](#contributing) 82 | 1. [Acknowledgements](#heart-acknowledgements) 83 | 1. [License](#license) 84 | 85 | # The Golden Rule: avoid coding wherever possible 86 | Be **optimally lazy**. There are only two principles: 87 | 88 | 1. The fastest way to finish a task is to do nothing 89 | * Ask yourself if you can live without it 90 | * Less code means less bugs 91 | * See also: 92 | * [You aren't gonna need it](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it) (YAGNI) 93 | * [Customer development](http://www.startuplessonslearned.com/2008/11/what-is-customer-development.html) 94 | * [Minimum viable product](http://www.startuplessonslearned.com/2009/08/minimum-viable-product-guide.html) (MVP) 95 | 1. The second fastest way to finish a task is to get someone else to do it 96 | * For example, this playbook is an example of using someone else's work to get ahead 97 | * Use [Node.js core API](https://nodejs.org/api/) if you can get away with it 98 | * Use pre-built pieces of code, such as [npm packages](https://www.npmjs.com/) 99 | * Make sure you use [high quality dependencies](#how-solutions-were-chosen) 100 | 101 | [(back to top)](#contents) 102 | 103 | # General 104 | This section covers general problems regardless of your development goals. 105 | 106 | ## Installing Node.js 107 | ### Goal 108 | Install Node.js. 109 | 110 | This sounds simple enough, but unfortunately the Node.js website makes you choose a version of Node.js to download. 111 | ### Solution 112 | Choose [Node.js v6](https://nodejs.org/dist/latest-v6.x/). It is in long term support (LTS), which means that further updates are mostly [limited to bug fixes and security updates](https://github.com/nodejs/lts#lts-plan). This gives you peace of mind against major new features popping up in Node.js while you build your app. 113 | 114 | Version 6 will stay in LTS for 18 months, and will switch to maintenance mode in April, 2018. 115 | 116 | [(back to top)](#contents) 117 | 118 | ## Development environment 119 | ### Goal 120 | 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. 121 | ### Solution 122 | Download and install these tools: 123 | * Editor: [Atom](https://atom.io/) 124 | * Atom packages/plug-ins: 125 | * [Package Installation script here](https://gist.github.com/talkahe/25d1f34d2aec3cf662b29309ec08635d) 126 | * `atom-beautify` ( `Ctrl/Cmd+comma` ➔ `Packages` ➔ Search for `atom-beautify` ➔ `Settings` ➔ toggle the `Beautify On Save` option for every language you want) 127 | * `atom-html-preview` (press `Ctrl/Cmd+P` in the editor to open the preview) 128 | * `fold-lines` 129 | * `platformio-ide-terminal` (terminal at bottom of editor) 130 | * `markdown-preview` (press `Ctrl/Cmd+Shift+M` in the editor to open the preview) 131 | * `linter` (A linter is a small program that checks code for stylistic or programming errors. [Available linters](http://atomlinter.github.io/) ) 132 | * `linter-jshint` (JavaScript linter) 133 | * `highlight-selected` (Double click on a word to highlight it throughout the open file.) 134 | * `minimap` (broad overview of code) 135 | * `minimap-cursorline` 136 | * `atom-typescript` (`.ts` support for atom) 137 | * `autoclose-html` 138 | * `double-tag` (edit HTML open and close tags simultaneously) 139 | * `color-picker` (highlight a color, right click, choose color-picker. Can view & edit colors visually) 140 | * `package-sync` (save atom packages across computers with a config file) 141 | * Version control: [git](https://git-scm.com/) 142 | * Repository (repo) hosting: [GitHub](https://github.com/) 143 | * [free private repos for students](https://education.github.com/) 144 | * Git GUI: [SourceTree](https://www.sourcetreeapp.com/) 145 | * API testing: [Postman](https://www.getpostman.com/apps) 146 | * Socket testing: [Socket.io tester](https://chrome.google.com/webstore/detail/socketio-tester/cgmimdpepcncnjgclhnhghdooepibakm?hl=en) 147 | 148 | [(back to top)](#contents) 149 | 150 | ## Workflow 151 | ### Goal 152 | Set up a brand new project. 153 | ### Solution 154 | 1. Create a new repo on GitHub 155 | * Choose Node under the gitignore settings when creating a repo 156 | * Choose to create a README.md file 157 | 1. Clone it to your computer using either a terminal command or SourceTree 158 | 1. Set up your [file and folder structure](#file-and-folder-structure) 159 | 1. Open a terminal window in your repo folder (or use the Terminal button when you open the repo in SourceTree) 160 | 1. Run `npm init` in your terminal to create a `package.json` file 161 | * Set your initial version to `0.1.0` (see also [version numbering](#version-numbering)) 162 | * Set the entry point to `src` (see also [file and folder structure](#file-and-folder-structure)) 163 | * For open source projects choose an MIT license by typing `MIT` when prompted for a license name 164 | 1. Run `atom .` in your terminal to launch Atom in your project folder 165 | 166 | [(back to top)](#contents) 167 | 168 | ## File and folder structure 169 | ### Goal 170 | Set up a file and folder structure that lets you add more complexity later, such as build and test systems. 171 | ### Solution 172 | 1. Create one subfolder: 173 | 1. `src`: place all your source code here 174 | 1. Create a file in the `src` sub-folder called `index.js` 175 | 176 | [(back to top)](#contents) 177 | 178 | ## Coding style 179 | ### Goal 180 | Develop a coding style that lets you share your code without embarrassment. 181 | 182 | A sloppy coding style reflects poorly on you. 183 | ### Solution 184 | Follow [Airbnb's Javascript Style Guide](https://github.com/airbnb/javascript) 185 | 186 | [(back to top)](#contents) 187 | 188 | ## Native modules and Windows 189 | ### Goal 190 | Fix errors related to `node-gyp` when you try to install an npm package. 191 | 192 | 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. 193 | ### Recommended solution 194 | Find another npm package that does the job in pure JavaScript. For example, [bcryptjs](https://www.npmjs.com/package/bcryptjs) is a drop-in replacement for the popular [bcrypt](https://www.npmjs.com/package/bcrypt) module. 195 | 196 | How to find alternatives: 197 | * 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 198 | * search online 199 | 200 | Make sure that your chosen alternative is a suitable replacement. Look for: 201 | * recently active contributors 202 | * good documentation 203 | * number of downloads 204 | 205 | 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. 206 | ### Alternative solution 207 | Do this **if and only if** you cannot find a suitable alternative npm package. 208 | 209 | Follow the Windows installation instructions at the [node-gyp README](https://github.com/nodejs/node-gyp#Installation). 210 | 211 | [(back to top)](#contents) 212 | 213 | # Web 214 | Read this if you are trying to build a web application. 215 | 216 | ## Technology stack 217 | ### Goal 218 | Choose a technology stack (e.g. server framework, database, front-end framework, hosting platform). 219 | ### Solution 220 | * Back-end: 221 | * Hosting: [Heroku](https://www.heroku.com/) (choose the "free dyno" option) 222 | * Server framework: [express](https://www.npmjs.com/package/express) 223 | * Sockets: [socket.io](https://www.npmjs.com/package/socket.io) 224 | * Database: PostgreSQL (host it on Heroku with the free option) 225 | * Object-relational mapping: [Sequelize](https://www.npmjs.com/package/sequelize) 226 | * Front-end 227 | * Domain: [Namecheap](https://www.namecheap.com/domains/registration.aspx) 228 | * Hosting: [CloudFlare](https://www.cloudflare.com) 229 | * JavaScript: [React](https://facebook.github.io/react) 230 | * Use [react-slingshot](https://github.com/coryhouse/react-slingshot) as a template. It sets up a project structure, an example app, and [Redux](https://github.com/reactjs/redux) as a state management system 231 | * Styling: [Bootstrap](http://getbootstrap.com/) 232 | 233 | [(back to top)](#contents) 234 | 235 | # Mobile 236 | This section covers problems commonly encountered with: 237 | * developing and distributing native mobile applications in JavaScript 238 | * serving mobile users for web applications 239 | 240 | I am seeking contributors for this section. 241 | 242 | [(back to top)](#contents) 243 | 244 | # Desktop 245 | This section covers problems commonly encountered with developing and distributing desktop applications. 246 | 247 | I am seeking contributors for this section. 248 | 249 | ## Multi-OS framework 250 | ### Goal 251 | Package and run your Node.js app as a desktop application on any operating system (OS). 252 | ### Solution 253 | Use [Electron](http://electron.atom.io/). 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. 254 | 255 | [(back to top)](#contents) 256 | 257 | # Packages 258 | This section covers problems commonly encountered with developing and publishing reusable packages. 259 | 260 | ## Publish to NPM 261 | ### Goal 262 | Shows how to publish your own module to npm and then install anywhere 263 | ### Solution 264 | 265 | - Module uniqueness, visit [npmjs](https://www.npmjs.com/) to insure your named module is the unique 266 | - Sign up account, by now, if no npmjs account, just sign up one which would be used to publish your module 267 | - First publish, enter your module dir, just type `npm publish` 268 | - Check publish, now, you have published your module, change to any other place, type `npm install ` to check whether could be installed successful! 269 | - Publish again, it's necessary to up module version by [Version numbering](#version-numbering) when you update the module and wish to publish again 270 | 271 | [(back to top)](#contents) 272 | 273 | ## Version numbering 274 | ### Goal 275 | Update version numbers in a way that indicates how significantly the package has changed for its users 276 | ### Solution 277 | Use [Semantic Versioning](http://semver.org/) (a.k.a. semver). 278 | 279 | - Increment your patch (0.0.x) version with `npm version patch` 280 | - Increment your minor (0.x.0) version with `npm version minor` 281 | - Increment your major (x.0.0) version with `npm version major` 282 | 283 | 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`. 284 | 285 | Here are the most important bits about semver: 286 | 287 | > Given a version number MAJOR.MINOR.PATCH, increment the: 288 | > 289 | > 1. MAJOR version when you make incompatible API changes, 290 | > 2. MINOR version when you add functionality in a backwards-compatible manner, and 291 | > 3. PATCH version when you make backwards-compatible bug fixes. 292 | > 293 | > How should I deal with revisions in the 0.y.z initial development phase? 294 | > 295 | > 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. 296 | > 297 | > How do I know when to release 1.0.0? 298 | > 299 | > 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. 300 | 301 | [(back to top)](#contents) 302 | 303 | ## Upcoming sections 304 | 305 | 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: 306 | 307 | * General 308 | * Understanding event driven programming 309 | * Clustering (solution: throng) 310 | * Password hashing (solution: bcrypt) 311 | * Saving exact and secure dependency versions (solution: --save-exact, --secure, and .npmrc) 312 | * Good documentation / READMEs 313 | * Debug logging (solution: debug) 314 | * Event emitter (solution: eventemitter3) 315 | * Testing 316 | * User analytics and app monitoring 317 | * Other analytics: keen.io, google analytics and kissmetrics, and key metrics 318 | * Promises and callbacks, async code execution (maybe asyncawait too) 319 | * Error handling: callback convention, Promise.catch, try/catch for sync code 320 | * Packages 321 | * Writing command line tools 322 | * Publishing to NPM 323 | * Web 324 | * Creating a REST API server (solution: Swagger) 325 | * Deploying serverless (solution: serverless and AWS Lambda) 326 | * IaaS vs PaaS vs BaaS vs FaaS/serverless 327 | * Application architecture (solution: single page apps with a back-end API server) 328 | * Handling server overload (solution: toobusy) 329 | * Rate limiting and prevent brute force logins 330 | * Authentication (solution: jsonwebtoken) 331 | * Don't run your server on port 80 or 443, use a reverse proxy 332 | * Security 333 | * SSL 334 | * Message queues and async function execution 335 | * Mobile 336 | * Immediate user feedback for server requests 337 | 338 | [(back to top)](#contents) 339 | 340 | ## Contributing 341 | Contributions are welcome! Here's how you can help: 342 | 343 | | If you want to ... | How to contribute | 344 | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 345 | | Ask for a recommended solution to a particular problem or goal | First, check the [Upcoming sections](#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. | 346 | | 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](#how-solutions-were-chosen). | 347 | | 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](#how-solutions-were-chosen). Because we are focused on finishing upcoming sections, we are only accepting improvements if they are **vastly** better than the current solution. | 348 | | Translate the Playbook | That's great! Please join the discussion in our [i18n GitHub Issue](https://github.com/HiFaraz/node-playbook/issues/20). | 349 | 350 | ### :heart: Acknowledgements 351 | Thanks to the following for helping with ideas and edits 352 | 353 | * [aem](https://github.com/aem) 354 | * [antony](https://github.com/antony) 355 | * [Calinou](https://github.com/Calinou) 356 | * [dodekeract](https://github.com/dodekeract) 357 | * [helloworld](https://github.com/helloworld) 358 | * [houjunchen](https://github.com/houjunchen) 359 | * [JTronLabs](https://github.com/JTronLabs) 360 | * [krokofant](https://github.com/krokofant) 361 | * [mateoKaradza](https://github.com/mateoKaradza) 362 | * [Morrisai](https://github.com/Morrisai) 363 | * [necenzurat](https://github.com/necenzurat) 364 | * [NicoPennec](https://github.com/NicoPennec) 365 | * [partounian](https://github.com/partounian) 366 | * [talkahe](https://github.com/talkahe) 367 | * [wli](https://github.com/wli) 368 | * [xxdavid](https://github.com/xxdavid) 369 | 370 | [(back to top)](#contents) 371 | 372 | ## License 373 | 374 | [![Creative Commons License](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) Faraz Syed, 2016 375 | 376 | Copyright (c) 2016 Faraz Syed. This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-sa/4.0/) 377 | 378 | [(back to top)](#contents) 379 | --------------------------------------------------------------------------------