codepath/nodejs_guides

Comprehensive open-source Node.js guides

CodePath Node.js Guides

Welcome to the open-source CodePath Node.js Guides. Our goal is to become the central crowdsourced resource for complete and up-to-date Node.js content and tutorials. Just take me to the notes!

Motivation

Ever been frustrated finding information on outdated one-off blog posts and tutorials that has since become irrelevant? How many times were you googling only to find your answer only on a 2 year old StackOverflow post? We believe there's got to be a better way. Why not have the community work together to create useful and detailed documentation for every aspect of iOS (or any platform)? There's absolutely no reason that we should have to make do with outdated, vague or un-editable content anymore.

Read about our mission to change the way engineers learn new technologies and we would love for you to get involved! In addition, we are a fledgling startup so if you like this guide and what we are trying to do, please consider following us on twitter @codepath.

nodejs_guides's Issues

Setting Up A New Project

• Glean all the fundamentals of getting a hello world express server up and running from the Setup wiki the prework and the week 1 assignment.
• Assume their environment is already setup

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

JavaScript: Inheritance

MDN has superior material on this [1,2]. There's not much need to rehash it, but it might be worthwhile to provide some focused & simple examples of creating a class with inheritance, constructor, static and instance methods and properties and an equivalent prototypal example with Object.create.

Also see Babel's class example

This is a bit of an overloaded tricky subject. Let's try and avoid the controversy and provide simple recommendations and additional information for people to decide for themselves.

• Common Inheritance Misconceptions

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Streams

1. Break the below into coherent sections
2. Explain unix pipes and their corollary with node.js streams (explaining the concept of node.js streams as well)
3. Explain the need for streams (memory pressure, decreased latency, CPU amortization & convenience)
4. Lead with .pipe examples
   • Emphasize that source streams can be piped to multiple destination streams
   • Show example of piping from multiple source streams (readable.pipe(writable, {end: false}))
5. Cover the basics: .read(), .write(), .pause(), .resume & events: 'data', 'close', 'error'
6. Mention briefly push vs pull-based streams and how Streams 2/3 uses pull streams
7. Mention how back-pressure is handled
8. Briefly explain buffers, link to a reference (docs or blog post or guide), and show String(buffer)
9. Show 2 simple as possible examples of consuming (read: piping) each of the 4 stream types. You should use the most common examples e.g., req/res, through, fs read/write.
10. Provide a common use case (e.g., A common type of duplex stream would be a WebSocket).
11. Strongly recommend working through the stream-adventure nodeschool.io workshop and provide a screen shot of the stream-adventure exercise selection menu.

Advanced section:

1. Explain object mode briefly, provide minimalist example and provide link to a more comprehensive explanation
2. Provide code samples on how to create your own streams (i.e., .push, _read, _write & _transform) and additional links
3. Show of JSON streaming example & explain !!LOUDLY!! how JSON.parse/stringify are the #1 cause of CPU blocking in node.js

The stream handbook is nice, but it's too verbose and needs more structure. In general the examples are good, so use them.

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Troubleshooting

1. Create a generic troubleshooting doc with some appropriate sections and cover common troubleshooting issues
2. Useless stack trace? => longjohn or turn on bluebirds long stack traces (include link to section in Debugging Guide)
3. Server crashing and not restarting? Use nodemon, refer to setup wiki
4. let requires strict mode error? Turn on strict mode in either babel (--optionals strict) or node's --use-strict
5. Link to the debugging guide and various other resources

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

why is the android robo in the reame

^

Control-flow

1. Define callback & show simple example
2. Explain the Callback Contract by providing examples (don't need to cover every point necessarily) and explanations for why they're important
3. Explain the benefits of promises over callbacks:
   • adopted into language
   • automatic error catching
   • hold value (.then can be attached any time)
   • .chainable
   • A verifiable spec that has all the benefits of the callback contract
4. Include a link to a more elaborate explanation
5. Cover the fundamentals of the promise API (.then(success, failure), .done(), .all(), .catch()) with very very simple commented examples
6. Describe the 3 common control-flow situations & provide examples:
   • parallel
   • series
   • branching (i.e., nesting a promise so it can have it's own independent flow)
7. Discuss that we'll be using bluebird for performance reasons and the need for the bluebird-nodeify package
8. Show async/await example of the 3 common control-flow situations
9. Show how async functions can be passed values, return values, return a promise and auto-catch (see here for reference)
10. Mention how bluebird.coroutine is mostly equivalent and can be used without babel (--harmony)

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Express & Middleware

Express

• Express hello world (links to corresponding express docs)
• routing examples (links to corresponding express docs)
• Rendering example (using ejs)
• encourage route & middleware modularization:

Route example

function getUsers(req, res, next) {
  // ...
}

function createUser(req, res, next) {
  // ...
}

module.exports = (app)=> {
  app.get('/users', getUsers)
  app.put('/user', createUser)
}

Middleware example

module.exports = (req, res, next) => {
  req.someProperty = true
  next()
}

Middleware

• app.use, ordering, function signature ((req, res, next) => {})
• in Express 4, routes are in the order they're added relative to other middleware
  • Show an example of 2 routes with the body-parser middleware in the stack between them
  • Point out how the first route can be used for streaming (no body parser) while latter will have req.body
• route middleware, encourage reusability & composability
• common middleware

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Project Generator/Workflow Guide

There are a lot of options out there. One thing I found challenging when first starting out was what a production level workflow looked like, I started out exploring the yeoman workflow:

http://yeoman.io/

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM @CrabDude

Package Recommendations

• Servers (in order): express, hapi, sails, koa, loopback
  • Ideally these would have at least 1 authoritative getting started with X blog post and 1 video
• Promises
  • bluebird (performance), babel's built-in language implementation , q (feature-filled)
• ORM
  • sequelize, mongoose, node-orms2, juggling db, bookshelf, waterline (from sails)
• utilities
  • lodash (mention mixins like string), request, lazy underscore
  • nconf for hierarchical configuration

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Babel

• Explain reason for using babel (it'll all be in V8 soon and eventually won't need it at all)
• Glean relevant information from setup guide for getting up and running
• Show how to run your server
• explain the difference between babel & babel-node
• Show how to compile to a dist directory and run the compiled server
• explain/list common transforms & show how to set them in CLI & babelrc

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Master List: Cliffnote Topic Requests

This is the master list of things that need to be added / improved on the cliffnotes. If you see an important topic missing here, please reply below!

Incomplete stubs that need attention to be completed (please help out if you can):

Streams
Control-flow
Troubleshooting
Setting Up A New Project
CLI
Things To Know
Babel
Modules & Packages
Debugging

A few topics we could use help developing cliffnotes for:

Coming soon...

More advanced broader topics that could use cliffnotes by experts:

Coming soon...

Third-party libraries:

Coming soon...

Any help starting these cliffnotes would be appreciated! Feel free to add other requests as an issue or to this thread! If you are interested in contributing, please check out the contributing guidelines to understand the philosophy of the guides.

Design Patterns

• require at top (core, package, file) then variables
• sync only during first tick => mark as Sync
• use promises => nodeify(), done(), return
• app as dependency injection
• middleware
• small modules
• export at top (single value) or bottom (multiple values)
• avoid parasitic (monkey patching the environment / runtime) code, except at app (top) level
• use js instead of JSON for configs (for comments)
• don't store state at the module level!!!! (export a constructor and store state in the instance)
• app lifecycle: require, configure, initialize, run (first tick contains: require, configure, start of initialize)

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Modules & Packages

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.

Filesystem

• file CRUD examples with streaming versions of CRU
• stat example, especially isDirectory
• fs.watch & chokidar examples
• Explain that there are Sync versions of everything that should ONLY BE USED on the first eventloop tick
• Show examples using songbird's promises
• Mention fs-extra

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Modules & Packages

• Give code examples of building a module (module.exports)
• Add disclaimer to user module.exports not exports
• Link to docs and include resolution pattern of require path (e.g. core, path & installed)
• Explain node_modules
• Explain package.json dependencies
• Show how to install & rm packages with versions & --save
• Explain the difference between global and local packages
• Show where to search for packages http://npmjs.com
• Explain semver with link and semver ranges (e.g., ^ & ~) and that ^ is default
• Link to package.json
• Explain package.json highlights

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Improve Javascript/Node markdown syntax highlighting

The Github syntax highlighting is much better than the CodePath syntax highlighting.

Debugging

• Show how to log stack traces
• Always keep original error:
  node promise.catch(e => { let error = new Error('Authentication failed') error.originalError = e })
• And use long stack traces both longjohn and bluebird's
• Show how to use node-inspector (node & babel-node)
• debugger; --debug & --debug-brk
• Recommend step debugging boxed in IDEs
• node-profiler
• node-webkit-agent
• node-block for watching event-loop latency
• nodetime
• new relic

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Things to Know

• A general dumping ground of unknown unknowns to help new developers avoid pitfalls and expose them to fantastically better perhaps less known things (like looking for packages first)
• node flags like --harmony --use-strict and --v8-options
• There's a package for that
• uncaughtException & the associated gotcha
• Why Node.js
• ...
• ...

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

Server Error on Auth

http://guides.codepath.com/nodejs/Authorization-&-Authentication

gives an "Internal Server Error", I'm assuming because of the "&"

/cc @nesquena

CLI

• Round out the existing CLI with all the necessary information to complete the prework
• Include a shoutout to commander as more popular and more feature-filled and it's variadic argument support

What success looks like: Succinctness and clarity. Less is more.
Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM

JavaScript: Basics

This should just be a collection of resources, probably mostly from MDN, but also some others currently here

What success looks like: Succinctness and clarity. Less is more.
This should just be a pared down collection of recommended references for learning the language.

Please assign to yourself before working on this.
/cc @NinjaSudo @philster @azoff @DiyahM