Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Promises (Bluebird) reading list

Promises reading list

This is a list of examples and articles, in roughly the order you should follow them, to show and explain how promises work and why you should use them. I'll probably add more things to this list over time.

This list primarily focuses on Bluebird, but the basic functionality should also work in ES6 Promises, and some examples are included on how to replicate Bluebird functionality with ES6 promises. You should still use Bluebird where possible, though - they are faster, less error-prone, and have more utilities.

I'm available for tutoring and code review :)

You may reuse all gists for any purpose under the WTFPL / CC0 (whichever you prefer).

If you get stuck

I've made a brief FAQ of common questions that people have about Promises, and how to use them. If you don't understand something listed here, or you're wondering how to implement a specific requirement, chances are that it'll be answered in that FAQ.


Bluebird will not work correctly (in client-side code) in older browsers. If you need to support older browsers, and you're using Webpack or Browserify, you should use the es6-promise module instead, and reimplement behaviour where necessary.



Many guides and examples fail to demonstrate Promise.try, or to explain why it's important. This article will explain it.

Error handling

Many examples on the internet don't show this, but you should always start a chain of promises with Promise.try, and if it is within a function or callback, you should always return your promises chain. Not doing so, will result in less reliable error handling and various other issues (eg. code executing too soon).


Functional (map, filter, reduce)


ES6 Promises

Odds and ends

Some potentially useful snippets:

You're unlikely to need any of these things, if you just stick with either Bluebird or ES6 promises:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment