{"id":15498115,"url":"https://github.com/bcomnes/node-handbook","last_synced_at":"2025-04-16T05:49:57.638Z","repository":{"id":144724231,"uuid":"36568966","full_name":"bcomnes/node-handbook","owner":"bcomnes","description":":camel: A js/node safari :monkey: :beginner:","archived":false,"fork":false,"pushed_at":"2019-04-07T21:44:02.000Z","size":36120,"stargazers_count":113,"open_issues_count":2,"forks_count":13,"subscribers_count":9,"default_branch":"gh-pages","last_synced_at":"2025-03-29T05:04:25.536Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/bcomnes/node-handbook#node-handbook","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcomnes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-30T17:52:07.000Z","updated_at":"2024-09-07T20:13:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"6af1ed1c-2f06-4613-8bc8-c59c5996a9f9","html_url":"https://github.com/bcomnes/node-handbook","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcomnes%2Fnode-handbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcomnes%2Fnode-handbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcomnes%2Fnode-handbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcomnes%2Fnode-handbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcomnes","download_url":"https://codeload.github.com/bcomnes/node-handbook/tar.gz/refs/heads/gh-pages","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249204827,"owners_count":21229808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T08:41:59.239Z","updated_at":"2025-04-16T05:49:57.606Z","avatar_url":"https://github.com/bcomnes.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# node-handbook\n\nLets learn node the node way! :dromedary_camel: :see_no_evil: :hatching_chick:\n\n![](img/sparkle.gif)\n\nIt's uncertain where this trek will take us, but we will try to strike a balance between instructional material, history, and philosophies on node, javascript, software, programming, engineering, communication, and tooling.\n\nWe may also cover a few other useful places to learn cool tools and skills like:\n\n- html\n- css\n- git\n- irc\n- linux/unix (aka \\*nix)\n- app deployment\n- people skills\n\n\n ```\n  ·      + 　　 　 . \n  ?　　　　· 　 · 　　.　 · 　　.　 \n   ˚  +  *  . .  　.　 .  　 ˚  +  *  . \n   .  ⋆ 　　　 ˚ .　.🚀🐢🚀 . \n   + ✷   ✦  .     +  .  　　 　　　　\n   　  +  .  ·  　  　 ✧ . 　 .\n```\n\u003e --- yoshuawuyts / Fishrock123 / substack\n\n\n## Required Provisions\n\n* A computer :camel: (hopefully running a flavor of unix)\n  * OS X will be easiest to use\n  * Linux and windows are a bit more difficult\n* Internet and a browser :globe_with_meridians:\n* some time and interest :bow:\n\nWe will be acquiring items and tools along the way.\n\n## How long is this adventure going to last?\n\nGetting through all the material is going to take time.  Visit the places that seem most interesting, and don't get stuck on something you find boring or overwhelming.  Programming is [more fun and effective as a hobby](https://twitter.com/substack/status/586438480164589568) and you will learn more if you treat it that way.\n\nDo take breaks and try to build something interesting.  Even if you fail, you will learn something.  Publishing your experiments feels good and creates breadcrumbs for others to learn from.\n\nDon't go at it alone.  Be open to companions along the way.  Offer collaborative opportunity to others who may be seeking similar experience, and try to be willing to offer help and contributions to others when it seems appropriate and useful to both parties.\n\nDon't live near anyone?\n\n![](http://bret.io/media/ownyourgram.com/igiRHQt1.jpg)\n\nThere is a vibrant and active community that is on-line at all hours of the day so you can remain isolated but still be connected with thousands of people.  Skip ahead to [#community](https://github.com/bcomnes/node-learnbook#community) to find possible avenues of interest, and places where you might meet other like minded people.\n\n# Getting started.\n\nBefore we get started, we need to be somewhat prepared to face what lies ahead.  In order to communicate with the local populous you need to learn how to speak and think javascript.\n\n## [Javascript for Cats](http://jsforcats.com)\nIf your a cat, like to have fun or learn like a cat, this will teach you the basics of javascript.\n\n[![](img/jsforcats.png)](http://jsforcats.com)\n\n## [Codecademy](http://www.codecademy.com/en/tracks/javascript)\nIf you tend to be a bit more serious, Codecademy's Javascript is also a good place to start.  Don't feel bad if you get bored and don't finish.  It's picking up the syntax that counts.\n\n[![](img/codecademy.png)](http://www.codecademy.com/en/tracks/javascript)\n\n## [nodeschool.io: javascripting](https://github.com/sethvincent/javascripting)\n\nWe will revisit [nodeschool.io](http://nodeschool.io/) in the near future, but for now the `javascripting` nodeschool adventure is a good place to start learning javascript.  It may be a bit steep for absolute beginners.  Read through the [`get going`](http://nodeschool.io/#get-going) section to get up and running.\n\nFor those who know their way around `npm` already:\n\n```sh\nnpm install -g javascripting\n\n```\n\n[![](img/javascripting.png)](https://github.com/sethvincent/javascripting)\n\n# What is javascript?\n\nJavascript is the programming language that your web browser comes with, but these days its becoming a lot more.  Its pretty okay.  Its not the best language and has a lot of warts, but it gets a lot right, and you don't really have a choice about using it or not (although this is changing, for better or for worse).  You shouldn't skip learning javascript though.\n\nIt was invented by Brendan Eich in the days of the mosaic browser and netscape: [JSJ The Origin of Javascript with Brendan Eich](https://devchat.tv/js-jabber/124-jsj-the-origin-of-javascript-with-brendan-eich)\n\n[![](img/eich.png)](https://devchat.tv/js-jabber/124-jsj-the-origin-of-javascript-with-brendan-eich)\n\n[Douglas Crockford](http://www.crockford.com) gave a good presentation that effectively answers the question: \"What is Javascript?\" in his 2012 \"Javascript: Your New Overlord\" presentation:\n\n\u003cfigure\u003e\n\u003cimg alt=\"Javascript: Your New Overlord\" src=\"img/crockford.gif\" /\u003e\n\u003cfigcaption\u003e\n\u003ca href=\"https://www.youtube.com/watch?v=Trurfqh_6fQ\"\u003e\nJavascript: Your New Overlord\n\u003c/a\u003e\n\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nYou should watch it!\n\n### ESWhat?\n\nAlso while we are on the topic, Javascript is the real world implementation of ECMAScript (abbreviated ES*, where * is the spec version), which is just a language specification e.g. a document that describes how it should work.\n\nThe current trend right now is to call the specs ES2015 (for ES6), ES2016 (for ES7) etc as a way to help promote quicker releases and access to newer language features.\n\nMore language features means more to learn for everyone.  The more everyone has to learn, the more intimidating starting out can be.\n\nES5 is a simple yet expressive language that we have right now.  Adding new features isn't guaranteed to improve the language (but there are quite a few welcomed features and data structures).  Be open about what to learn, and picky about what you choose to use.\n\nYou don't need to read these right now, but here are the last couple specs:\n\n- [ES5](https://es5.github.io)\n- [ES6 Draft (ES2015?)](http://people.mozilla.org/~jorendorff/es6-draft.html)\n- [ES7 (ES2016?)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_7_support_in_Mozilla)\n- [ES\\* Compatibility Table](https://kangax.github.io/compat-table/es6/)\n- http://www.bloomberg.com/graphics/2015-paul-ford-what-is-code/\n\n# What is node?\n\nNode was created by [Ryan Dahl](http://tinyclouds.org).  He has since pulled a [Mark Pilgrim](http://www.diveintomark.link) and [HTTP 410](http://en.wikipedia.org/wiki/Mark_Pilgrim#.22Disappearance.22_from_the_Internet)'d himself from the INTERNET, but occasionally will post interesting undocumented code projects to his [github](https://github.com/ry) or [post to the node mailing list](https://groups.google.com/forum/#!activity/nodejs/2JvBi5ikhDgJ).\n\nThe best way to understand what node is to listen to Ryan describe it himself.\n\n[![Ryan Dahl: Original Node.js presentation](img/ry1.gif)](https://www.youtube.com/watch?v=ztspvPYybIY)\n\n[Ryan Dahl: Original Node.js presentation](https://www.youtube.com/watch?v=ztspvPYybIY)\n\n[Ryan Dahl: Original Node.js presentation Slide Deck](doc/jsconf.pdf) (pdf)\n\n[![Ryan Dahl Talk - NodeConf Theatre 2012.ogv](img/ry2.gif)](https://www.youtube.com/watch?v=GhFrlX0LdFA)\n\n[Ryan Dahl Talk - NodeConf Theatre 2012.ogv](https://www.youtube.com/watch?v=GhFrlX0LdFA)\n\n[Ryan Dahl Talk NodeConf Theatre 2012 Slides](doc/nodeconf2012.pdf) (pdf)\n\n## A few links about node's missing father\n\n- https://news.ycombinator.com/item?id=4892174\n- https://news.ycombinator.com/item?id=7064470\n- http://shitryandahlsays.tumblr.com/\n- https://www.youtube.com/watch?v=SAc0vQCC6UQ\n- https://github.com/ry/v8worker\n- http://siliconangle.com/blog/2012/01/31/how-a-vacuum-cleaner-salesman-became-the-new-king-of-node-js/\n- http://www.quora.com/What-is-happening-to-Joyent-and-how-does-it-affect-NodeJS\n- https://gist.github.com/cookrn/4015437\n\n### What is Node: The Links\n\nSome links discussing issues related to what node tries to solve and other general readings.  *Caution* some of these are overly advanced... maybe revisit these if the subject interests you.\n\n- [About Node.js®](http://nodejs.org/about/)\n- [A little holiday present: 10,000 reqs/sec with Nginx!](http://blog.webfaction.com/2008/12/a-little-holiday-present-10000-reqssec-with-nginx-2/)\n- [The C10K problem](http://www.kegel.com/c10k.html)\n- [Wikipedia: Event Loops](https://en.wikipedia.org/wiki/Event_loop)\n- [Wikipedia: Asynchronous I/O](https://en.wikipedia.org/wiki/Asynchronous_I/O)\n\n# How to get node\n\nThere are lots of ways to install node.  Lets visit some of the better ways of this contentious topic.\n\n## In theory\n\nNode needs the following two things to really work effectively:\n\n### A build toolchain\n\nA build toolchain is a complicated set of programs that let you build software from source.  Usually building software from source means building an executable binary from raw C and C++ source files and libraries.  Node needs a toolchain in order to build native addons (e.g. programs written in c that node modules sometimes needs to communicate with).\n\n**Examples**\n\n- [Xcode](https://developer.apple.com/xcode/)\n- [Visual Studio](https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx)\n- [GNU GCC](https://gcc.gnu.org/)\n- [CLANG](http://clang.llvm.org/)\n\n### The node.js runtime\n\nThis is node iteself!  It provides things like the `node` command/runtime, and usually comes with `npm` bundled with it.\n\n\n### Python2\n\nNode requires python2 to build native addons.\n\n### A general purpose package manager\n\nA package manager is optional, but having one available and set up is extremely helpful.  Package managers install software for you, automatically and unattended.  They go out and download the programs you want, as well as the other programs required to run them, then take all the necessary steps to put them into the right place where you can use said programs.  Some people can't be bothered to use a package manager because you need to learn a little bit about how they work, but you will become a more powerful developer if you learn to use a traditional package manager.\n\n**Examples**\n\n- [homebrew](http://brew.sh/)\n- [apt-get](http://manpages.debian.org/cgi-bin/man.cgi?query=apt\u0026sektion=8)\n- [yum](http://yum.baseurl.org/)\n- [pacman](https://wiki.archlinux.org/index.php/Pacman)\n- [chocolatey](https://chocolatey.org/)\n\n## OSX\n\n\u003ca href=\"https://jamesfriend.com.au/pce-js/\"\u003e\u003cimg src=\"img/osx.png\" height=\"175\"\u003e\u003c/a\u003e\n\nThe only prerequisite to installing node is that you have a copy of [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12).  Its free and the only place to get it is from App store (boooo).  This fills the toolchain requirement on the OS X side of things.\n\n\u003ca href=\"https://itunes.apple.com/us/app/xcode/id497799835?mt=12\"\u003e\u003cimg src=\"img/xcode.png\" height=\"175\"\u003e\u003c/a\u003e\n\nOSX Terminal.app is pretty great for everything you need to do (although historically it used to suck).  Just use OSX's terminal unless you have a reason not to.\n\n\u003ca href=\"https://en.wikipedia.org/wiki/Terminal_(OS_X)\"\u003e\u003cimg src=\"img/terminal.png\" height=\"175\"\u003e\u003c/a\u003e\n\nThere are two great options to install `node` on OSX: Homebrew and the Official Installer.\n\n### [Homebrew](http://brew.sh)\n\n\u003ca href=\"http://brew.sh\"\u003e\u003cimg src=\"img/brew.png\" height=\"175\"\u003e\u003c/a\u003e\n\nHomebrew is a lightweight package manager for OS X.  Homebrew:\n  - downloads and installs Unix CLI programs from source code\n  - keeps track of which programs you installed and at what version\n  - updates your programs when updates are available\n  - download non-npm programs and utilities\n\nUntil npm has packages for all external dependencies, having `brew` installed can be really helpful.\ns\nVisit the [Homebrew](http://brew.sh) website for the latest instructions on how get\n`brew` installed.\n\nOnce you have homebrew installed installing node is as easy as running:\n\n```sh\n$ brew install node\n```\n\nTo get new releases of node in the future download run:\n\n```sh\n$ brew update\n$ brew upgrade node\n```\n\nEasy.\n\nA quick brew `101` so that you know what you just did:\n  - `/usr/local` is a special unix folder where 'userspace' (e.g. not managed by the OS)programs can be safely installed.  Since homebrew was installed by the user by hand, it is a userspace program.\n  - Homebrew turns `/usr/local` into a git repo\n  - `brew` uses \"Formula\" written as simple ruby scripts to download, build and install programs to `/usr/local/Cellar`\n  - The active version of a program installed by `brew` is symlinked to `/usrlocal/{binlib,...}`\n  - `brew update` updates the `/usr/local` repo so that you have the latest 'Formula' available.\n  - All Formula can be built from source, but most have precompiled 'Bottles' (a.k.a binaries) to save time and battery power.\n  - Old versions of programs can be installed by going back into the git history.\n\nA few more links discussing the merits of homebrew:\n  - [to install node via Homebrew or not?](http://www.reddit.com/r/node/comments/37ui2to_install_node_via_homebrew_or_not/)\n\n### [The official node installer `node-v*.pkg`](https://nodejs.org/download/)\n\n[![](img/osxinstaller.png)](https://nodejs.org/download/)\n\nEasy.  You go to the node website, you [download the .pkg](https://nodejs.org/download, and install it.  It installs to the same location that homebrew installs to: `usrlocal/bin`.\n\n## Linux\n\nRunning Linux? (:+1: btw)\n\n![](img/stop.gif)\n\nDon't just reach for your systems package manager!\n\nLinux distributions almost universally ship painfully dated versions of node and npm (unless you are running something like [Arch Linux](https://www.archlinux.org)), and install them in ways that make them a total pain to use for the sake of 'stability'.\n\nThis sucks.\n\nLuckily there is a comprehensive resource on how to add software channels that have updated versions of node to common package mangers:\n\n[Installing-Node.js-via-package-manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager)\n\nBasically it boils down to this:\n\n### Add an updated node repo to your package manager\n\n- [nodesource/distributions](https://github.com/nodesource/distributions)\n\nYour linux distribution will dictate which package manager you use.\n\n### Configure npm to `-g` into `/usr/local` and fix permissions\n\nDon't sudo with npm!  (even -g).  Set up `npm` so that it works without sudo:\n\n[Fixing npm permissions](https://docs.npmjs.com/getting-started/fixing-npm-permissions)\n\nSetting `npm` to install to `/usr/local` is the correct place for `npm` to install global library binarys to.  It is in all user path's by default, and is the conventional well known location to look in.\n\nIf you are stuck in userland on a shared system and you don't have permissions to modify `/usr/local`, you can configure `npm` to install `-g` libs right into your home directory and add the resulting folder to your $PATH.  Only do this if you don't have access to `/usr/local`.\n\n## Windows\n\n\u003e Windows is very important.  Just like PHP\n-- [Ryan Dahl](https://youtu.be/jo_B4LTHi3I?t=56s)\n\n[![](img/bill.gif)](http://nodejsreactions.tumblr.com/post/113606988159/corporates-attempting-to-woo-developers-jumping-on)\n\nOn windows, pretty much stick with the official installer:\n\n[Official Installer](https://nodejs.org/download/)\n\nThere are a few package managers on windows which you are free to explore on your own time:\n\n- [Chocolatey](https://chocolatey.org)\n- [Scoop](https://github.com/lukesampson/scoop)\n\nWindows support for node is pretty good.  Windows support for most npm modules is pretty bad.\n\nYou will also need to install a free version of Visual Studio for building modules that have native addons:\n\n[Visual Studio Express](https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx)\n\nas well as python2 installed:\n\n[python2](https://www.python.org/downloads/)\n\nFor up to date windows caveats, see [Microsoft/nodejs-guidelines](https://github.com/Microsoft/nodejs-guidelines)\n\n# How to know node\n\nNow that we have seen a bit about the history and motivations behind node, lets actually visit the necessary materials to actually understand node.\n\n## [The Art of Node](https://github.com/maxogden/art-of-node#the-art-of-node)\n\n[![](img/art-of-node.png)](https://github.com/maxogden/art-of-node#the-art-of-node)\n\nWritten by [Max Ogden](http://maxogden.com),\n\n\u003cimg src=\"img/max.gif\" alt=\"thanks http://substack.net/art\" height=\"200\"\u003e\n\n*An image of Max holding a bag of fish for some reason.  Probably to lure cats. Image by [substack](http://substack.net/art)*\n\n[maxogden/art-of-node](https://github.com/maxogden/art-of-node#the-art-of-node) gives a thorough explanation of how node works, how to write node flavored javascript, callbacks and async programming, writing and using modules and how to be apart of the node/js community and do your best.  Its full of insight and clear reasoning, but when you are new to js and/or node, all of the subtleties can fly by pretty quickly.  **It's a short and easily digestible read, that you should probably read through a few times**.\n\n## [Node.js in Action](http://www.manning.com/cantelon/)\n\n[![node.js in action image cover](img/inaction.jpg)](http://www.manning.com/cantelon/)\n\n([2nd Edition Coming Soon](http://www.manning.com/cantelon2/))\n\nWritten by a group of early prolific node.js module developers, this book is *totally great* and *somewhat flawed*, and a bit dated at this point as well.  It has a great set of examples though, and it's \"hello world\" app is the well-known [socket.io](http://socket.io) chat server.\n\nIt covers the basics of all the well known [Visionmedia](https://github.com/visionmedia)  modules (e.g. [express](http://expressjs.com), [mocha](http://mochajs.org), [connect](https://github.com/senchalabs/connect#readme), [jade](http://jade-lang.com), [ejs](http://www.embeddedjs.com) etc...).  You will learn to use all of these early node tools, including core node modules, async programming, testing, templating, CLI programs, and even node clustering from this book through the various included projects and examples.\n\nDespite the fact that many of the modules discussed have changed their APIs, this is still a great reference and useful for learning node.\n\nUnfortunately, this great collection of knowledge is tombed away in a book (*we should change that though*).  Get the book if you can.\n\n**What this book does well:**\n\n- Introduction to node, events async programming and flow control\n- [socket.io](http://socket.io) examples\n- npm modules: publishing and consuming\n- Module resolution and loading (a.k.a. [require('foo')](https://nodejs.org/api/modules.html#modules_module_require_id))\n- http\n- ORMs and Databases\n- Middleware and [Connect](https://github.com/senchalabs/connect)\n- [Express](http://expressjs.com) photo hosting and microblogging app\n- Testing (mostly Mocha)\n- EJS and Jade templating\n- Node application deployment\n- System Calls\n- Raw TCP/IP\n- CLI Tools\n\nFocus on the first and last 1/3 of the book, and don't sweat the middle 1/3rd (express/connect).\n\n## [Nodeschool.io](http://nodeschool.io/)\n\n\u003ca href=\"http://nodeschool.io/\"\u003e\u003cimg src=\"http://bcomnes.github.io/node-learnbook/img/schoolhouse.svg\"\u003e\u003c/a\u003e\n\nNodeschool is a free resource that offers lessons and tutorials on tons of topics, mostly relating to node and js.  The key is that the lessons are written for `node` and you install them with `npm` (usually).\n\nThey were designed to be taught at community events around the world, but you can learn on your own at home if there isn't an event going on nearby.\n\n### [Node School Core](http://nodeschool.io/#workshopper-list)\n\nStart with [learnyounode](https://github.com/workshopper/learnyounode) which can be installed with\n\n```sh\nnpm i -g learnyounode\n```\n\n![](img/learnyounode.png)\n\n(No, not [learnyouhaskell](http://learnyouahaskell.com/), that lives on a different planet)\n\nAfter this, brush up on your `git` in `git-it`:\n\n```sh\nnpm i -g git-it\n```\n\nGit is a super important tool to know, use and love.  Its like a checkpoint system in a video game but for text files on your computer.  Check all of your projects into git, and throw them up on github.  It's a great way to publish your work, and keeps a backup of everything you do!\n\n![](img/git-it.png)\n\nFinally, wrap your head around `npm`\n\n\n```sh\nnpm i -g how-to-npm\n```\n\n`npm` is node's package manager.  Its like [`pip`](https://pypi.python.org/pypi/pip), [`gem`](https://rubygems.org/) or [`cabal`](https://www.haskell.org/cabal/) for javascript.\n\n![](img/how-to-npm.png)\n\n# Callbacks Deconstructed\n\nTODO: Lets get a bunch of super simple examples of callbacks and work our way up to understanding what runs async and what doesn't all the way up to `process.nexTick()`.\n\n## More reading\n\n- http://nrn.io/view/javascript-common-pitfalls\n- http://neversaw.us/2014/12/20/classifying-asynchrony/\n\n# Callbacks visualized\n\nCallbacks are confusing at first, because you are writing functions that accept variables that seemingly come out of nowhere.\n\nThese variables that your callback accepts come from the internals of the function accepting the callback function!\n\nBefore we get into it, remember:\n\n- Async functions return immediately\n- If your code needs the results of an async function, that code needs to live in the scope of that async function's callback.\n- Code that comes after an async function must complete before the async function calls its callback function.  This the \"Run to completion\" guarantee.\n- Functions that take a callback must be async or not async.  Don't write a function that takes a callback that does not perform async work as this will break the \"Run to completion\" guarantee.\n- [You can't `return` values from an async callback like you might think.](http://nodejsreactions.tumblr.com/post/56341420064/when-i-see-some-code-that-returns-a-value-from-an)\n\nLets take a look:\n\n![](img/visualcb1.png)\n\n1. First, we define `fs.readFile`.  Typically you import this as a module (e.g. `var fs = require('fs')`), but for this example we want get an idea of what is going on internally.  The code to actually read files is omitted, but at the end of the function we see that the `callback` argument is invoked as a function (e.g. `callback(err, data)` where the `err` and `data` variables would be defined inside the function somewhere when reading the file.)\n\n2. Next we invoke `fs.readFile` passing in a string containing the path to the file we wish to read, encoding options, and a callback function that accepts `err` and `data` arguments to match the arguments that the `callback` placeholder defines in step 1.  The file is read and the placeholder callback is replaced with our callback function that we passed as an argument.\n\n3. After `fs.readFile` is done trying to read the file, it calls our callback function, passing to it `err` and `data` as arguments and our callback function then begins execution.  If there was no error when reading the file, `err` will be `undefined`/falsy so we can easily test for errors and handle them, or pass them along.\n\nLets clean it up a little.\n\n![](img/visualcb2.png)\n\nWe replace the anonymous function with a named function `logger` that we pass as the callback.  It's nearly the exact same thing as the first example, except now the function can be implemented independently from where we invoke fs.readFile.\n\nOk, so it's not always practical to go digging around the internals of a module to locate the callback signature (e.g. the arguments) that it expects of your callback.  This is where the module's `README.md` comes in.\n\nHow did we know `fs.readFile` expects a callback with `(err, data)` arguments?  We look it up!\n\n**[node.js API docs: fs.readFile](https://nodejs.org/api/fs.html#fs_fs_readfile_filename_options_callback)**\n\n![](img/readfile.png)\n\nModules should come with a `README.md` with similar documentation.  If it doesn't have this, maybe look around for one that does.\n\nWe can write our own callback functions just as easily.\n\n![](img/visualcb3.png)\n\nHere we write an async function that wraps the fs.readFile async function.\n\nWe write a function that accepts a callback as the last argument.  We do some asynchronous work inside of it, modify the output and then pass it into our callback.\n\nEasy!\n\nWell, in theory.  Callbacks take a bit of practice, but hopefully we can visualize callback flow and how variables and functions are passed around.\n\n## Callback you later\n\nYou can read more about callbacks, but the best way to learn how to use them is to read and write lots of them!  While your doing that, peruse through these lovely links.\n\n- [maxogden/art-of-node#callbacks](https://github.com/maxogden/art-of-node#callbacks)\n- [callbackhell.com](http://callbackhell.com/)\n- [Why callback hell can be your friend.](http://jondavidjohn.com/why-callback-hell-can-be-your-friend/)\n- [Node In Action: 3.2 Asynchronous Programming Techniques](#nodejs-in-action) p.46\n- [Eloquent Javascript: Http callbacks](http://eloquentjavascript.net/17_http.html#p_8Shcg3/WzI)\n\n## I Promise\n\n- https://blog.domenic.me/youre-missing-the-point-of-promises/\n- http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript\n- https://github.com/petkaantonov/bluebird#what-are-promises-and-why-should-i-use-them\n- https://spion.github.io/posts/why-i-am-switching-to-promises.html\n\n# Javascript the hard parts\n\nJavascript is easy to learn, but hard to master.  It's a flawed language with lots of subtle pitfalls to be navigated.  These materials will help you master the more subtle and difficult aspects of the language.\n\n\n##  [Nodeschool.io](http://nodeschool.io/): Tie it all together\n\nIf you haven't already, finish up the core nodeschool workshops.  The last two are the most conceptually difficult:\n\n`scope-chains-closures` teaches you all about scopes and closures!\n\n```sh\nnpm i -g scope-chains-closures\n```\n\n\u003cimg src=\"img/scopes.png\" heigh=\"300\"\u003e\n\n`stream-adventure` teaches you about streams.  This is a good place to start, but will leave you with a lot of questions.\n\n```sh\nnpm i -g stream-adventure\n```\n\n\u003cimg src=\"img/stream.png\" heigh=\"500\"\u003e\n\n## [Effective Javascript](http://effectivejs.com)\n\n[![](img/ejs.jpg)](http://effectivejs.com)\n\n**REQUIRED READING**\n\n[Effecitve Javascript](http://effectivejs.com) is an excellent book focusing only on Javascritpt the Language.  It has answers and clarifications for the more confusing aspects of the languages, explains the prototype chain in a clear way, and covers the more advanced aspects of JS.  The only downside is the cost of the book. A+\n\n## [Eloquent Javascript](http://eloquentjavascript.net)\n\n[![](img/eloquent.png)](http://eloquentjavascript.net)\n\nThis is a free e-book (paper version is available too).  It seems to reside somewhere between [Effective Javascript](#effective-javascript) and [Node.JS in Action](#nodejs-in-action) with an environment agnostic approach to writing javascript.  It has a lot of projects in it that run closer to your more traditional programming textbook.\n\n## [Javascript: The Good Parts](http://www.amazon.com/exec/obidos/ASIN/0596517742/wrrrldwideweb)\n\n\u003ca href=\"http://www.amazon.com/exec/obidos/ASIN/0596517742/wrrrldwideweb\"\u003e\u003cimg src=\"img/thegoodparts.jpg\" height=\"400\"\u003e\u003c/a\u003e\n\nJSTGP is one of Douglas Crockfords claim to fame (he also wrote down the [JSON](http://json.org) spec). It's pretty old at this point, and a difficult, dense and terse read.  But its still really good, and has one of the better explanations about the different styles of object composition and inheritance (AKA Object Oriented Programming... or something kind of like it):\n\n### JSTGP:The good parts\n\n- Pseudoclassical Inheritance\n- Prototypal Inheritance\n- Functional Inheritance\n- Talking about the bad and awful parts of js is straightforward and interesting.\n- Setting the expectation of critical understanding and critique of different aspects of Javascript.\n\n### JSTGP:The bad parts\n\n- The train track diagrams, while correct, literally don't help you think or understand how to write better JS.  You get as much out of it as a you do completing a maze.\n- The regex stuff might confirm your understanding, but don't try to learn regex from this book.\n- Its discussion on callbacks.  It doesn't even give one good example!  It was written before JS was widely known for its ability to perform cooperative multitasking.\n\nYou will no doubt have questions about some of the suggestions in the book.  It was written as [ES5](https://es5.github.io) was still not widely available.  Quite a few of the polyfills noted in the book are actually widely available functions and methods... so double check [MDN](https://developer.mozilla.org/en-US/) to see if its just a built in function now.\n\n# `npm` stuffs\n\n\u003ca href=\"https://www.npmjs.com/\"\u003e\u003cimg src=\"http://bcomnes.github.io/node-learnbook/img/npm.svg\"\u003e\u003c/a\u003e\n\n`npm` is a package manager.  If you have something (anything!) that could be apart of a larger project, you should version it and put it on `npm`.  Its *the* package manager for javascript, and is becoming the package manager for HTML and CSS components.\n\ntl;dr `npm` helps you download dependencies and publish reusable pieces of code/assets/software.\n\n## How do I use `npm`?\n\nIn addition to the [how-to-npm](#node-school-core) nodeschool adventure, `npm` has a great getting started page:\n\n[![](img/npmgettingstarted.png)](https://docs.npmjs.com/getting-started/what-is-npm)\n\n- [npm getting started](https://docs.npmjs.com/getting-started/what-is-npm)\n\nBut here are the short notes version:\n\n### Using `npm` to start a project of your own\n\n```\n$ mkdir newproj ; cd newproj\n$ git init\n$ npm init\n```\n\nAs we develop and use modules, we save them with:\n\n```sh\n$ npm i request --save\n# e.g. install the request module and save it to package.json\n```\n\nWhen you are finally ready to put it out into the world\n\n```sh\n$ npm publish\n```\n\n### `npm` with existing projects\n\nIf you clone in a project with a `package.json`, typically this is where you start:\n\n```sh\n$ git clone project@url.git ; cd project\n$ npm i\n# i is short for install\n# `npm install` would also work\n```\n\nThis is downloads the dependencies of the project into a folder called `node_modules`.  The `node_modules` folder should be added to your `.gitignore` file.\n\nA good next step is to test the project:\n\n```sh\n$ npm test\n# this tests the module\n```\n\nTests help ensure that others can help make changes and contributions the the module.  There are no automated module interface testing tools, so project specific tests are the best thing we have right now.\n\nOften you can start the module by running.\n\n```sh\n$ npm start\n```\n\nFinally, we can inspect other actions that project author added to the `package.json` `scripts` field:\n\n```sh\n$ npm run\n```\n\nThis lists of other actions we can take on the module.\n\n## What *IS* `npm` really?\n\n`npm` is arguably more interesting than node itself:\n\n`node` is a tiny V8 javascript runtime engine with bindings to a set of high performance asynchronous `C` libraries.\n\n`npm` is a system for authoring, packaging, and consuming reusable bits of code and assets, AND the worlds largest open source software repository:\n\n\u003ca href=\"http://www.modulecounts.com\"\u003e\u003cimg src=\"img/npmgrowth.png\" width=\"1260\"\u003e\u003c/a\u003e\n\nIt's analogous to a lego machine that produces unlimited copies of whatever kind of lego you can think of.\n\n\u003e I want programming computers to be like coloring with crayons and playing with duplo blocks. --[Ryan Dahl](https://news.ycombinator.com/item?id=4310723)\n\n`npm` works better when using it when modules are small, focused bits of code that solve one problem well (instead of kitchen-sink, do-all modules).\n\n- [docs.npmjs.com: What is npm?](https://docs.npmjs.com/getting-started/what-is-npm)\n- [Understanding npm](https://unpm.nodesource.com/)\n\n[![](img/npmuniverse.gif)](https://unpm.nodesource.com/)\n\n## Why is `npm` different than {gem,pip,bundler,cpan,etc}?\n\n`npm` does a few things differently:\n\n### Local packages by default\n\nWhen you `$ npm install` a package with `npm`, it installs to the `node_modules` folder specific to your project.\n\nIn nearly every other programming language, the package manager installs to a system wide (or user wide) dependency folder that all projects use.  This runs into all sorts of permission errors and complexities that make it difficult to write software.  Local-by-default `node_modules` solve:\n\n- Permission errors when users without admin access try to install project dependencies.\n- Inconsistent and opaque module loading directories.\n- Cognitive disconnect and confusion of where your modules are loading from.\n- Eliminates the need for `$ENV` variables.\n\nSystem wide dependency repositories are **Global Variables**.  Nearly every language has systematic hacks to get around this issue like [bundler.io](http://bundler.io/) and [virtualenv](https://virtualenv.pypa.io/en/latest/). None of these actually solve the problem that local-by-default `node_module` solves.\n\nThis is an important concept. Read more about it here:\n\n\u003ca href=\"https://github.com/maxogden/art-of-node#how-require-works\"\u003e\u003cimg src=\"img/node_modules.png\" width=\"1748\"\u003e\u003c/a\u003e\n\n- [art-of-node: How `require` works](https://github.com/maxogden/art-of-node#how-require-works)\n- [Folder Structures Used by npm](https://docs.npmjs.com/files/folders)\n- [Node API Docs:#modules_loading_from_node_modules_folders](https://nodejs.org/api/modules.html#modules_loading_from_node_modules_folders)\n- [Node.js In Action: (p.43) Reusing modules in the node_modules folder](#nodejs-in-action)\n\n\n### Nested dependencies by default\n\nIn most languages, if you depend on dependency `A@2.0` and `B@1.0`, and `B@1.0` depends on `A@1.0`, you are in [dependency hell](https://en.wikipedia.org/wiki/Dependency_hell).  You are unable to satisfy your dependency tree in a way that functions.\n\nNode and `npm` allow for nested dependencies.  That means, your app gets `A@2.0` and `B@1.0` gets `A@1.0`.\n\n[![](img/nested-vs-flat-deps.png)](http://maxogden.com/nested-dependencies.html)\n\nHow does this magic work?  See:\n\n- [Nested Dependencies](http://maxogden.com/nested-dependencies.html)\n- [node packaged modules](http://maxogden.com/node-packaged-modules.html)\n\nNested dependencies solve the following issues:\n\n- Dependency hell: Every dependency gets the dependencies it wants at the version it wants.\n- Allows you to update your dependencies without worrying about breaking consumers of your module.\n- Allows dependencies to update their dependencies without worry of breaking your module.\n- Breaks undefined ties to global version state.\n\nNested dependencies introduce considerable complexity, and work is ongoing to improve its reliability. See what `npm@3` is doing to improve this: [npm@3.0.0 cangelog](https://github.com/npm/npm/releases/tag/v3.0.0).\n\n### Encourages experimentation through module diversity\n\nMany languages discourage the publishing of reusable code through various roadblocks (but primarily cultural ones).\n\n`npm` encourages publishing as much as possible.  Publishing a module is a single command, and mostly automated.\n\nThis is unprecedented.\n\nAs a result, there are tons of bad modules.  There are lots of good ones too.  This solves the following issues:\n\n- Community complacency with mediocre, monolithic packages.  Everyone feels free to make something better, even if it sort of already exists.\n- Stale standard libraries with lots of roadblocks in the way of improvements.  Javascript doesn't have a standard library, and doesn't need one.\n- Over designed and complicated do-all module APIs.  The simplest and best modules usually win eventually!\n- Denies [Architecture Astronauts](http://www.joelonsoftware.com/articles/fog0000000018.html) of Air, as they are side-stepped by multiple working modules during their never ending design debates.\n- Lack of of solution diversity for different problem domains.  Usually there are 3 - 100 different modules to choose from.\n- Reduces unwarranted individual influence over language features and community culture to a minor degree.  This is still a major cultural factor, but an open module system helps reduce this a little.\n\n### More reading:\n\n- [mikeal on node_modules](https://gist.github.com/sukima/3854887#node_modules-in-git\n)\n\n## `.package.json` is here to save you\n\n[![](img/package.json.png)](https://github.com/bcomnes/node-learnbook/blob/gh-pages/package.json)\n\nThe `package.json` is the source of truth about your module.  It describes critical aspects of the module, like the name, version, license and entry point into the program.\n\nIt is worth reading the `npm` docs page about this file in its entirety:\n\n[Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json)\n\nHere are some keys of interest:\n\n- [`main`](https://docs.npmjs.com/files/package.json#main): this is the name of the entry point of your application.  When requiring the module, you get whatever this file `exports` or `module.exports`.  When reading a modules source code, this is the file you look at first.\n- [`bin`](https://docs.npmjs.com/files/package.json#bin): sometimes modules will include a executable bin.  These get specified here.  These end up in the `./node_modules/.bin` folder and are available to the commands defined in the `scripts` field.  They also get installed to your `$PATH` if you installed with the `-g` flag.\n- [`scripts`](https://docs.npmjs.com/misc/scripts): this is where you define scripts.  You should always include the following scripts in your module (if appropriate):\n  - `test`: the command used to test your module\n  - `start`: the command to run your module\n- [`dependencies`](https://docs.npmjs.com/files/package.json#dependencies): these list off modules and their version ranges that your module needs in order to work.\n- [`devDependencies`](https://docs.npmjs.com/files/package.json#devdependencies): these are modules needed to test, build and otherwise develop your module.  Dependencies that are not required at runtime should live here.  This includes all utility programs, test runners, task runners and build scripts.\n- [`license`](https://docs.npmjs.com/files/package.json#license): This is the [SPDX license identifier](https://spdx.org/licenses/) for the module.  `npm` complains if you leave this out.\n\n## `devDependencies` and `npm` scripts shield you from opinions.\n\n*AKA, how to navigate the world of javascript development tools without going crazy.*\n\n\u003ca href=\"http://gruntjs.com/\"\u003e\u003cimg src=\"http://bcomnes.github.io/node-learnbook/img/grunt.svg\" width=\"100\"\u003e\u003c/a\u003e\u003ca href=\"http://gulpjs.com/\"\u003e\u003cimg src=\"img/gulp.png\" height=\"150\"\u003e\u003c/a\u003e\u003ca href=\"https://www.gnu.org/software/bash/\"\u003e\u003cimg src=\"img/bash.png\" width=\"100\"\u003e\u003c/a\u003e\n\nThere are two factors to this problem.\n\n- There are tons of new javascript development tools to choose from with cool looking logos that get people really excited.\n\n- It isn't totally obvious what the best way to install and use these tools are.\n\n### `tl;dr` of using build tools are:\n\n1. Install and save them as `devDependencies` in your package.json (e.g. `npm i grunt --save-dev`)\n2. Nail down the tool's project specific use in the `scripts` field.\n3. Install the accompanying CLI with -g **only** when you feel the need to have it available system wide, and don't ever ask other developers to install a global tool for project specific use cases.\n\nIf a module comes with a `bin`, that ends up in the `.\\node_modules\\.bin` folder.  `.\\node_modules\\.bin` shouldn't be in your $PATH.  When `npm` runs a command out of the `.package.json` `scripts` field, it supplements the search path with `.\\node_modules\\.bin` so that they are available for use from that interface.\n\nThis can be referred to as `node_modules\\.bin` PATH hoisting.\n\nBy hiding your toolchain behind a common interface, you shield yourself and other developers from these boring, toolchain details.  Nobody actually cares what tools you used when they are looking to make a fix or change to your module, and you are not doing anyone any favors by promoting your favorite tools in this context by asking people to install a `-g` tool to work on your module.\n\n**Read this article to learn more:**\n\n- [A Facade for Tooling with NPM Package Scripts](http://bocoup.com/weblog/a-facade-for-tooling-with-npm-scripts/)\n\n### Grunt, Gulp, Broccoli... Bash?\n\n\u003e[![](img/ggb.gif)](http://nodejsreactions.tumblr.com/post/82300463325/grunt-gulp-broccoli)\n\u003e\nGrunt, Gulp, Broccoli --[nodejsreactions.tumblr.com](http://nodejsreactions.tumblr.com/post/82300463325/grunt-gulp-broccoli)\n\nNot every project needs a full task runner.  Single purpose node utilities piped together with bash is a great way to get things done and should be considered.\n\n- [Why we should stop using Grunt \u0026 Gulp](http://blog.keithcirkel.co.uk/why-we-should-stop-using-grunt/)\n- [How to Use npm as a Build Tool](http://blog.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/)\n\nSometimes projects benefit from a task runner.  In these projects, use a task runner.\n\n[![](img/grunts.gif)](https://www.youtube.com/watch?v=YQwYNca4iog)\n\n- https://gist.github.com/substack/8313379\n\n### A tool of your own\n\nWhen you decide you need a custom dev Tool, follow this general design process:\n\n1. Write your tool as a node module that can be tested and consumed by other node modules, in a generic and independent way.\n2. Write a CLI interface that consumes the library, and bundle it with the library (bonus points if you write it to accept [`stdin` so that it can be piped together](https://nodejs.org/api/process.html#process_process_stdin) with other tools.)\n3. Finally, write a separate, ecosystem specific module that requires your generic library and provides the correct interface to grunt/gulp etc.\n\nStep 3 is often optional.  Write these interface with task runners that you care about, and support contributors who want to write an task-runner specific interface for your module.\n\n- https://github.com/jlevy/the-art-of-command-line\n- https://github.com/alebcay/awesome-shell\n\n## Utopia `npm`\n\nGlobal and environmental dependencies are an anti-pattern because it adds endless complexity to the process of writing and deploying applications.\n\nThe `npm` community has some really big ideas about what `npm` can and could do better.  It has often been the tradition that you write a program, that talks to a web server like [apache](http://www.apache.org/) through [CGI](https://en.wikipedia.org/wiki/Common_Gateway_Interface) and also connects to a database that is assumed running.\n\nThese are all massive assumptions on your applications part.\n\nModern day ops teams have seen the value in codifying all of this server and service state using things like [chef](https://www.chef.io/chef/) and [puppet](https://puppetlabs.com/).  Automating servers to achieve the correct state so that your application can run is great, but your app is still getting bundled without vital organs to make it work.\n\nUtopia `npm` is the idea that, with a working copy of `npm` and a project repository with a `package.json`, you can deploy your application by simply running the module's contract:\n\n```\n$ npm install ; npm test ; npm start\n```\n\nFor example, instead of running a DB as a server, [LevelDB](https://github.com/google/leveldb) is consumed no differently than any other library in your application:\n\n- [levelup](https://www.npmjs.com/package/levelup)\n- [leveldb-handbook](https://github.com/substack/leveldb-handbook) (incomplete :cry:)\n\n\u003e Running a big, well-known database service has an ineffable heaviness to it: they bind to a custom port and the service must already be running before your program will work. Worse, if you install the database from a package manager like apt-get, the database will be auto-daemonized and put into your init scripts. Good luck hunting down where it decided to put the configuration file. -- substack: [leveldb-handbook](https://github.com/substack/leveldb-handbook)\n\nInstead of downloading source dependencies and building them, they are packaged as pre-built binaries:\n\n- [levelup](https://github.com/Level/levelup)\n- [electron-prebuilt](https://github.com/mafintosh/electron-prebuilt)\n- [go-ipfs](https://www.npmjs.com/package/go-ipfs)\n- ...\n\nThese are just some examples of projects that facilitate packaging non-js assets as `npm` dependencies.  This is an important design principle to keep in mind when building apps and modules.  The more you can package into `npm`, the easier it will be to use your app or module.\n\nWhile the above examples are great, practical examples of patterns we can use today, these ideas are much larger than just versioning everything with `npm`.\n\n### JS.os?\n\n[![](img/xkcd.js.png)](http://xkcd.com/1508/)\n\n\u003ca href=\"https://node-os.com/\"\u003e\u003cimg src=\"img/nodeos.png\" height=\"100\"\u003e\u003c/a\u003e\n\n- [Node.OS](https://node-os.com/)\n- [Runtime.js](http://runtimejs.org/)\n\n[![](img/bandd.gif)](https://www.destroyallsoftware.com/talks/the-birth-and-death-of-javascript)\n\n- [The Birth and Death of Javascript](https://www.destroyallsoftware.com/talks/the-birth-and-death-of-javascript)\n\n# Semver\n\nSemver is the versioning scheme of the `node` community.  Its not perfect, but it works mostly okay:\n\n```\nmajor.minor.patch\n```\n\nbut you can also think about it like this\n\n```\nbreaking.feature.bugfix\n```\n\nYou start at version `1.0.0`, but sometimes people start modules at `0.0.1` to indicate :construction:experimental:construction: modules.\n\nThese links explain it pretty well.\n\n- [Semantic Versioning 2.0.0](http://semver.org/)\n  [![](img/semanticv.png)](http://semver.org/)\n- [Semver ftw!](http://semver-ftw.org/)\n- [The semantic versioner for npm](https://docs.npmjs.com/misc/semver)\n- [package.json#dependencies](https://docs.npmjs.com/files/package.json#dependencies)\n\nIn your `package.json`, you can specify your dependencies using semver ranges.\n\nThe default range is:\n\n```\n^version \"Compatible with version\" See semver(7)\n```\n\nThis range (in theory), should get you module patches that improve or fix bugs, and don't \"break\" the module interface in a range.  In practice, sometimes they break anyway.  This is why tests are critical.\n\nTools exist to help facilitate this patching process:\n\n- [next-update](https://www.npmjs.com/package/next-update): run your tests against available updates without touching the current dep versions.\n  [![](img/next-update.png)](https://www.npmjs.com/package/next-update)\n- [npm.click](http://npm.click/#/): inspect a `package.json` for outdated packages.\n  [![](img/click.png)](http://npm.click/#/)\n- [David. DM](https://david-dm.org/): automatically fetches package versions status from a github url.\n  [![](img/david-dm.png)](https://david-dm.org/)\n- [Semver Calculator](http://semver.npmjs.com)\n\nThis is an area that needs improvement and automation tools.\n\n# ... [WIP]\n\nStill pulling together the primordial ooze below.\n\n# Node in the browser?\n\nIn node, you have access to the `require` keyword that lets you load modules out of your ethereal `node_modules` folder.  This lets you write your programs in tiny, reusable modules of code.\n\nBrowserify is a program that lets you write javascript programs using the `require` system.  Instead of running the resulting programs in `node`, browserify peforms a \"build-step\" and outputs a bundle that you serve up for a browser to run.\n\n- [Browserify-handbook](https://github.com/substack/browserify-handbook)\n- http://wzrd.in/\n- https://github.com/thlorenz/browserify-shim#multi-shim-example-including-dependencies\n\nBrowserify's scope is fairly limited compared to traditional front-end frameworks, as a result there are quite a few other tools that do similar things plus a whole lot more.  Don't fall for it!  [YNGNI!](http://c2.com/cgi/wiki?YouArentGonnaNeedIt)  Except when you do.\n\n- https://github.com/substack/browserify-handbook#browserify-middleware-enchilada\n\n# Write your tests, clean your lint\n\nA module isn't complete without tests.  Modules are fairly small, so 100% coverage is generally a modest goal to reach.\n\nTests force to you clearly define your module's interface, and allow for internal improvements to be made while ensuring external consumers don't break.\n\nTesting your module will a mix of the following types of tools:\n\n- Testing harness: some set of functions that keep track of how many tests are run and if they pass or fail.\n- TAP Reporter: TAP is machine friendly.  TAP reporters are machines that make your TAP output human friendly.\n- Assertion library: this provides set of functions that are used to compare what actually happened to what you want to happen.  Sometimes this comes along with the testing harness.\n- Linter: This tool will perform static analysis on your code and point out mistakes, syntax errors, code smells or style issues.\n- Formatter: Formats code so that its is formatted consistently.\n- Continuous Integration (CI): You run your tests as you develop the module, but you can also have free services test your code for you.\n- Coverage: Running your coverage tools along with your tests lets you keep track of which portion of your code is tested.\n\n## `tape` it down\n\n[![](img/tape_drive.png)](https://www.npmjs.com/package/tape)\n\nThere are a lot of testing frameworks out there.  For most modules, [tape](https://github.com/substack/tape) is a great choice.  It's similar to writing tests in other languages like `go` and `python` so your ability to write tests will remain portable.\n\nHere are some reasons why `tape` is great:\n\n- Test results are output as [TAP](https://testanything.org/)\n- Works in a browser, so you can test for browser compatibility\n- Works like any other module.  You install it and require it into your test files.\n- Does not introduce non-standard language keywords, like `describe`\n- Provides a conservative but usefdul set of test assertions by default\n- Does not extend default object prototypes in your testing environment\n- Very stable, simple and complete\n\nSome links on using tape:\n\n- [tape's readme](http://npmjs.com/tape)\n- [how I write tests for node and the browser - substack](http://substack.net/how_I_write_tests_for_node_and_the_browser)\n- [testling on tape](https://ci.testling.com/guide/tape)\n\nHere's some tape tests\n\n```js\nvar test = require('tape')\n\nvar testString = 'normally i would be imported too'\nfunction foo() {\n  return testString\n}\n\ntest('lets test the foo function', function(t) {\n  setTimeout(function() {\n    t.equal(foo(), testString, 'foo() returns testString')\n  }, 100)\n})\n\ntest('lets test the foo function', function(t) {\n  t.notEqual(foo(), 'boop', 'foo() returns testString')\n})\n```\n\n- [finnp/node-travisjs](https://github.com/finnp/node-travisjs)\n\n\n# Event Emitters\n\nWhere do I go to learn these?\n\n# Inheritance, Composition, and the Prototype Chain\n\nAKA OO AKA Object Oriented, AKA :ghost::ghost: programming in Javascript.  Also prototypes.\n\nOO Programming is a way of organizing and writing code that breaks code up into \"classes\" that allow you to create object factories that create object instances that have instance specific properties and methods (aka a property of an object that is a function).\n\nJavaScript doesn't subscribe to the purely object oriented world-view like other language (e.g. Java or Objective C).  Object orientation is a valid, common and occasionally ideal way to organize code, but other times its not necessary.\n\nJavascript lets you write code in a object oriented way.  In fact, it lets you do it a number of different ways.  This is a blessing, and a curse.  While it allows for OO, often in a less verbose syntax than pure OO languages, you will have to learn all the different ways of writing OOJS in order to really do it effectively, as well as read code of other authors.\n\nMore often than not, you will find popular javascript libraries opt for the less ideal OO style for some reason.  There is no good explanation for this other than OO programming is currently a predominant coding paradigm, and certain OO JS styles resemble classical OO more than other more ideal OOJS styles.\n\nIts best to try to understand all the different OO styles, their strengths and weaknesses, and mix and match the parts that work with the problem domain you are attempting to solve.\n\n[Douglas Crockford](http://www.crockford.com) wrote the book on the different types of object oriented inheritance you can have in JavaScript in 2008, and he boils it down to three types:  **(Pseudo)classical**, **Prototypal**, and **Functional**.  This breakdown is required reading and can be found in [JavaScript: The Good Parts](#javascript-the-good-parts).\n\n[Eric Elliott](http://ericleads.com) revisits this issue in 2014 and breaks this issue down even more in [Programming JavaScript Applications](http://chimera.labs.oreilly.com/books/1234000000262/index.html)(Now a free e-book!)  Eric identifies the techniques used in each of Doug's OO styles, explains how they work and what they are good and not so good for, and introduces **Fluent-Style** JavaScript and the concepts of [stamps](https://github.com/stampit-org/stampit).\n\n[![](/img/eric.jpg)](http://chimera.labs.oreilly.com/books/1234000000262/index.html)\n\nWhile its worth reading Eric and Doug's take on OOJS, lets check out a quick reference of the different strategies.\n\n- https://medium.com/javascript-scene/what-is-webassembly-the-dawn-of-a-new-era-61256ec5a8f6\n- https://medium.com/javascript-scene/the-two-pillars-of-javascript-ee6f3281e7f3\n- https://medium.com/javascript-scene/the-two-pillars-of-javascript-pt-2-functional-programming-a63aa53a41a4\n- https://medium.com/javascript-scene/common-misconceptions-about-inheritance-in-javascript-d5d9bab29b0a\n\n## (Pseudo)Classical\n\n## Prototypical\n\n## Functional\n\n## Mixing the three\n\n# Whats the deal with Streams?\n\n- [Streams handbook](https://github.com/substack/stream-handbook)\n  \u003e Streams can help to separate your concerns because they restrict the implementation surface area into a consistent interface that can be reused.\n- [through](https://github.com/dominictarr/through)\n- [through2](https://github.com/rvagg/through2)\n- [duplexify](https://github.com/mafintosh/duplexify) - asynchronously assign readable and writable\n- [on streams1 vs 2-3](https://github.com/dominictarr/through/issues/37#issuecomment-129340097)\n- [pull stream](https://github.com/dominictarr/pull-stream)\n- [stephenplusplus/stream-faqs](https://github.com/stephenplusplus/stream-faqs)\n- https://nodejs.org/en/blog/feature/streams2/\n- https://dl.dropboxusercontent.com/u/3685/presentations/streams2/streams2-ko.pdf\n- https://iojs.org/api/stream.html\n- https://nodejs.org/api/stream.html\n- https://github.com/nodejs/readable-stream\n- https://strongloop.com/strongblog/whats-new-io-js-beta-streams3/\n- http://stackoverflow.com/questions/21538812/what-is-streams3-in-node-js-and-how-does-it-differ-from-streams2\n- https://github.com/joyent/node/issues/5860\n- https://nodejs.org/docs/v0.11.5/api/stream.html\n- http://brycebaril.github.io/streams2-presentation/#/21/7\n- https://www.npmjs.com/package/through2-spy\n- https://www.npmjs.com/package/stream-meter\n- https://github.com/brycebaril/node-stream-spigot\n- https://www.npmjs.com/package/through2\n- https://www.npmjs.com/package/through2-filter\n- https://www.npmjs.com/package/stream-spigot#star\n- https://twitter.com/rvagg/status/608577853601398784\n- https://iojs.org/api/stream.html#stream_simplified_constructor_api\n- http://words.jessekeane.me/front-end-streams/\n- https://cloud.githubusercontent.com/assets/37303/5728694/f9a3e300-9b20-11e4-9e14-a6938b3327f0.png\n- https://github.com/calvinmetcalf/streams-a-love-story\n- http://streams.how/\n- https://nodesource.com/blog/understanding-object-streams/\n- http://dominictarr.com/post/145135293917/history-of-streams\n\n# What makes modules small(µ)?\n\n- http://substack.net/node_aesthetic\n- http://substack.net/many_things\n- https://github.com/Raynos/http-framework\n- http://maxogden.com/a-month-of-modules.html\n- http://substack.net/finding_modules\n- https://github.com/substack/node-mkdirp/blob/master/index.js\n- http://www.ustream.tv/recorded/46670615\n- https://gist.github.com/substack/68f8d502be42d5cd4942\n- https://en.wikipedia.org/wiki/Turtles_all_the_way_down\n- https://gist.github.com/substack/5075355\n- http://0fps.net/2013/01/22/commonjs-why-and-how/\n- https://en.wikipedia.org/wiki/Modular_programming\n- https://gist.github.com/dominictarr/2401787\n- https://github.com/felixge/node-style-guide\n- http://www.quora.com/Whats-the-correct-way-to-write-nodejs-modules-There-seems-to-be-discrepancies-between-experts-like-substack-dominictarr-vs-the-newd-constructor-style-of-V8-optimization-recommendations-What-gives\n- https://github.com/openopensource/openopensource.github.io\n- https://github.com/ngoldman/open-2-contributing\n- https://github.com/yoshuawuyts/knowledge\n- https://github.com/npm-dom\n\n\u003e When applications are done well, they are just the really application-specific, brackish residue that can't be so easily abstracted away. All the nice, reusable components sublimate away onto github and npm where everybody can collaborate to advance the commons. -- [James Halliday-substack.net/how_I_write_modules](http://substack.net/how_I_write_modules)\n\n# Node.js and io.js Anthropology\n\n- http://blog.izs.me/post/104685388058/io-js\n- https://gist.github.com/maxogden/d96123138522c84cdb25\n- http://tableflip.io:1234/\n- https://github.com/iojs/io.js/issues/37\n- https://nodesource.com/blog/was-this-trip-really-necessary\n- https://twitter.com/rvagg/status/598605393636429825\n- https://twitter.com/mikeal/status/598595967928008705\n- https://github.com/nodejs/node\n- https://www.youtube.com/watch?v=UbYiFLf7MpU\n- https://github.com/nodejs/io.js/issues/1664#issuecomment-101828384\n- https://www.youtube.com/watch?v=hZJCnT7E1ts\n- http://tableflip.io:12345/\n\n# Tools to write Node\n\n# Spellcheck for Javascript\n\n# All the badges\n\n# Hex Stickers\n\n[![](img/hex-spec.png)](https://github.com/terinjokes/StickerConstructorSpec)\n\nTo be consistent with node's emphasis on small, interchangeable modules, somehow a hex sticker specification was created.  Other than looking super cool, and evenly dividing up valuable laptop surface real estate, one could understand hex stickers as node conventions actualizing as a distributed, shared community culture/art project.  By following a few simple, basic rules, everyone can create an interesting and useful piece of the puzzle that works nicely together to make up the whole while progressing the commons.  In this case, tessellating stickers across a laptop or water bottle without any wasted space!\n\n[![](img/school-hex.png)](http://nodeschool.io/hexdex.html)\n\n[Nodeschool's Hexdex](http://nodeschool.io/hexdex.html)\n\n[![](img/hexbin.png)](http://hexb.in/)\n\n[Hexb.in](http://hexb.in/) Hex sticker registry\n\n## A hex sticker of your own\n\nIt's pretty easy to make hex stickers.\n\n- [stickermule.com](https://www.stickermule.com/): Order die-cut stickers and ensure that they understand the correct dimensions of the stickers.\n- [hexi.pics](https://hexi.pics/help_en): a website dedicated to creating hex stickers.  Lets you trivially create hex stickers and order them.\n  [![](img/hexi.png)](https://hexi.pics/)\n\n## Hex Sticker Standard\n\nOh yes.  You heard right, a sticker standard.\n\n[![](img/hex-standard.png)](http://terinjokes.github.io/StickerConstructorSpec/)\n\n[Stickers Standard](http://terinjokes.github.io/StickerConstructorSpec/)\n\n[“How standards are made on small scale”](http://dybskiy.com/laptop-sticker-standard/): A nice little history of the spec.\n\n\u003e We quickly agreed that there should be a standard for them and that the most useful one seems to be 2”x1.75” hexagons. I tweeted it and the reaction was way more amazing than I expected.\n\n[![](https://c1.staticflickr.com/1/720/21399375139_05d8981b19_b.jpg)](https://www.flickr.com/photos/bretc/21399375139/in/dateposted-public/)\n\n[![](http://hexb.in/assets/laptop.png)](http://hexb.in/sticker.html)\n\n# An adventure of your own\n\nResources for teaching others and writing nodeschool adventures.\n\n# JS is the worlds polyglot assembly language now\n\n- http://bellard.org/jslinux/\n- https://github.com/jashkenas/coffeescript/wiki/List-of-languages-that-compile-to-JS\n- https://brendaneich.com/2015/06/from-asm-js-to-webassembly/\n- https://medium.com/javascript-scene/what-is-webassembly-the-dawn-of-a-new-era-61256ec5a8f6\n- https://medium.com/javascript-scene/why-we-need-webassembly-an-interview-with-brendan-eich-7fb2a60b0723\n\n# ES6 and Beyond\n\n- https://medium.com/@brianleroux/es6-modules-amd-and-commonjs-c1acefbe6fc0\n- http://espadrine.github.io/New-In-A-Spec/es6/\n- https://en.wikipedia.org/wiki/ECMAScript\n- http://blog.izs.me/post/25906678790/on-es-6-modules\n- http://tomdale.net/2012/01/amd-is-not-the-answer/\n\n# Frameworks\n\n- http://lebron.technology/\n- http://hapijs.com/\n- http://expressjs.com/\n- https://github.com/Raynos/http-framework\n- https://github.com/Raynos/mercury\n- https://jshttp.github.io/\n\n# Haters gonna hate\n\n[![](img/egg.gif)](http://nodejsreactions.tumblr.com/post/74845429937/every-why-node-js-sucks-article-ever)\n\n\u003e Every “why Node.js sucks” article ever --[nodejs reactions](http://nodejsreactions.tumblr.com/post/74845429937/every-why-node-js-sucks-article-ever)\n\nNode has its share of weak points.  Articles that hate on it generally miss these points.  A good way to learn about a tool is to analyze its criticism.  Does it have merit?  Is it correct?  Is the the stated issue as bad as the critic makes it out to be?\n\n- [![](img/idiot.gif)](https://www.youtube.com/watch?v=1e1zzna-dNw)\n\n  [Biz of Tech: Node.JS Is Stupid And If You Use It So Are You](https://www.youtube.com/watch?v=1e1zzna-dNw)\n  \n- [Should you Learn Node js in 2017](https://www.youtube.com/watch?v=ahXOaHv9XYo)\n\n# html + css\n\n- Dive into html5\n- HTML5 and css Jon Ducket\n\n# Community\n\n- irc\n- github\n- twitter\n- conferences\n- gitter/slack?\n- http://lin-clark.com/blog/2014/07/01/authoring-nodejs-workshopper-lessons/\n- http://nodeschool.io/\n\n# Mastering git\n\n- orily git\n- git for 5 year olds\n\n# Electron?\n\n- yay desktop apps\n- [electron handbook](https://github.com/bcomnes/electron-handbook)\n- https://github.com/sindresorhus/awesome-electron\n\n# Sharing your ideas\n\n:sunglasses:\n\n- http://www.macwright.org/big/\n- https://github.com/maxogden/slides\n\n\n## School of Substack\n\n- https://www.youtube.com/watch?v=84PE6EF3YWY\u0026list=FLd8cLeIEVcsbhyX9FDph-Jg\u0026index=3\n- https://github.com/substack/dnode\n- https://github.com/substack/upnode\n- https://github.com/substack/fleet\n- https://github.com/substack/seaport\n- http://substack.net/multi_server_continuous_deployment_with_fleet\n- http://substack.net/semver_your_services_with_seaport\n- http://substack.net/shared_rendering_in_node_and_the_browser\n\n# Native addons\n\n- https://medium.com/@nodesource/c-add-ons-for-node-js-v4-be5d48832933\n\n# IRC\n\n- https://gist.github.com/maxogden/8610086\n- http://nodeirc.info\n- http://blog.izs.me/post/30036893703/policy-on-trolling\n\n# Link Dump\n\nThis document was created  after amassing a large collection of node related links helpful to learning and understanding node.  Here is a partial linkdump until the rest of the guide can be written.\n\n\n\n- http://nikhilm.github.io/uvbook/threads.html#core-thread-operations\n- https://github.com/nodejs/node-v0.x-archive/issues/5132#issuecomment-15432598\n- https://github.com/sindresorhus/awesome\n- https://github.com/sindresorhus/awesome-nodejs\n- https://gist.github.com/staltz/868e7e9bc2a7b8c1f754\n- https://github.com/kriskowal/gtor\n- https://gist.github.com/jhclark/2845836\n- http://i.imgur.com/k0t1e.png\n- https://github.com/essdot/js-lessons\n- https://github.com/shama/base-element\n- http://coodict.github.io/javascript-in-one-pic/\n- https://github.com/hughsk/disc\n- https://github.com/reddit/reddit-mobile/issues/247\n- http://www.finnpauls.de/streams-editor/\n- https://github.com/finnp/streams-editor\n- http://dominictarr.com/post/25516279897/why-you-should-never-write-a-package-manager\n- https://gist.github.com/chrisdickinson/0a236ce62097c806113d#file-wip-md\n- https://gist.github.com/rgbkrk/91b40941a38daf700e61\n- http://browserify.org/articles.html\n- https://medium.com/@mjackson/universal-javascript-4761051b7ae9\n- http://www.learnenough.com/command-line\n- https://certsimple.com/blog/deploy-node-on-linux\n- https://github.com/denysdovhan/bash-handbook\n- http://mafintosh.com/learning-javascript.html\n- https://gist.github.com/chrisdickinson/3212df99d53851261597\n- https://git.cryto.net/Squatconf/Talks/src/master/accepted/day2/lessons-learned-presentation.md\n- https://github.com/felixrieseberg/windows-build-tools\n- https://github.com/a0viedo/demystifying-js-engines\n- https://nolanlawson.com/2016/08/15/the-cost-of-small-modules/\n- https://medium.com/@Rich_Harris/small-modules-it-s-not-quite-that-simple-3ca532d65de4#.tlkjx37nj\n- https://github.com/ahdinosaur/mad-science-handbook\n- https://nodesource.com/blog/eleven-npm-tricks-that-will-knock-your-wombat-socks-off/\n- https://web.archive.org/web/20160903203552/https:/twitter.com/izs/status/764295673625784320\n- https://github.com/nodejs/node/commit/da2f4b2dc429df120188c5633ac3bd6f4a3c5373\n- https://gwenbell.com/dt-interview/ (http://web.archive.org/web/20170501055359/https://gwenbell.com/dt-interview/)\n- https://twitter.com/BrendanEich/status/773400732305358848\n- http://npm.anvaka.com/#/\n- http://web.archive.org/web/20150216184318/https://docs.npmjs.com/misc/faq#if-npm-is-an-acronym-why-is-it-never-capitalized\n- https://github.com/ungoldman/awesome-browserify\n\n\n\u003e TC39 is powerless to ever remove [all the badness in JS].  All they can do is add more crap on top of it and they are busy doing that for you.\n\u003e - https://youtu.be/O9AwYiwIvXE?t=12m35s Douglas Crockford\n\n\u003e But if you work with a well defined subset of Javascript, you can write good programs.\n\u003e - https://youtu.be/O9AwYiwIvXE?t=12m46s Douglas Crockford\n\n\nhttp://archive.fo/ZMNgr NPM's api in a few tweets\n\n\n## Some more recent bickerings\n\n- Zeldman complains people builds apps instead of web pages: http://archive.fo/0uXJG\n- Frontend centric responds: http://archive.fo/Cc1pn\n- Alex Russel chimes in: http://archive.fo/raW9J\n- Mikeal responds http://archive.fo/PaapG\n- Mikeal threads some decent explainations, completely devoid from the original complainers persective: http://archive.fo/yUM6z\n- Why node is the way it is, from the perspective of a 2019 Izs:  http://archive.fo/i8n8x\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcomnes%2Fnode-handbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcomnes%2Fnode-handbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcomnes%2Fnode-handbook/lists"}