Guide · Open source
How to use bluebird: install, basics and when to skip it
Updated · written with AI from the project's own documentation and checked against our catalogue data
Bluebird is a JavaScript promise library that adds features and utilities on top of standard promise behavior. This guide explains what it does, how to install it through a package manager, and when it makes sense to use it. It also explains why the README recommends native promises for most new work.
Bluebirdpetkaantonov/bluebird · ★ 20.5k · MIT Install options & downloads Quick start
- 1Decide if bluebird fits. Check whether you have a legacy codebase, a very old browser target, end-of-life Node.js, or a need for promise debugging. If none apply, the README recommends native promises.
- 2Read the getting started guide. Open the getting started page on the bluebird website for installation and setup instructions.
- 3Install through your package manager. Follow the package-manager method in the official docs for your Node.js or browser project.
- 4Use the API reference. Look up methods and behavior in the bluebird API reference while you write code.
- 5Enable warnings to find bugs. If you are tracking down promise bugs, use bluebird's warnings or monitoring features as described in the docs.
- 6Ask questions on StackOverflow. For usage help, post on StackOverflow with the promise and bluebird tags rather than the GitHub issue tracker.
What is bluebird and what problem does it solve?
A promise is an object that represents a result that will arrive later, such as data from a network request. Bluebird is a library for working with promises and it adds extra features and utilities on top of the standard promise behavior.
The project describes itself as a fully featured promise library with a focus on innovative features and performance.
Should you use bluebird or native promises?
The README's first advice is to use native promises instead if at all possible. Native promises have been stable in Node.js and browsers for a long time, and most utilities bluebird offers, such as .map, have native equivalents.
The maintainers say bluebird is currently only recommended if you need to support very old browsers, end-of-life Node.js, or as an intermediate step to use its warnings and monitoring to find bugs.
- Choose bluebird for legacy codebases that already depend on it.
- Choose bluebird if your project must support very old browsers or end-of-life Node.js versions.
- Choose bluebird when you want its warnings or monitoring to track down promise bugs.
- For new projects on modern browsers or supported Node.js versions, use native promises.
Install bluebird
The source describes a package-manager install method. Prerequisites are Node.js or a browser environment. The README's install instruction is to clone the repository, though the source does not list the package name or the exact package-manager command, so check the bluebird website for the current install steps.
The website linked from the README has a getting started page at bluebirdjs.com/docs/getting-started.html.
git clone https://github.com/petkaantonov/bluebirdUse the API reference
The full documentation lives on the bluebird website. The API reference is at bluebirdjs.com/docs/api-reference.html and covers the methods the library provides.
If you are working with the older 2.x line, the README points to a separate 2.x branch of the repository for its documentation and files.
Get help and report issues
The GitHub issue tracker is only for bug reports and feature requests. For help using the library, the README asks you to post on StackOverflow under the tags promise and bluebird.
The README also lists a mailing list and an IRC channel for questions.
What people use it for
- Maintaining an older application that already uses bluebird for its promise utilities.
- Supporting very old browsers in a project that cannot rely on native promises.
- Running a service on an end-of-life Node.js version where native features are limited.
- Using bluebird's warnings to locate unhandled or misused promises during debugging.
Frequently asked questions
Is bluebird free to use?
Yes. Bluebird is released under the MIT License, which permits use, copying, modification and distribution, including commercial use, provided the copyright notice and license text are included. The software is provided as is, without warranty.
What do I need to run bluebird?
The source lists Node.js or a browser environment as the prerequisites. The README also notes that the library has been tested in old browsers such as IE8 through BrowserStack.
How do I install bluebird?
The source says the install method is a package manager, and the README's listed command is to clone the repository with git. Check the official getting started guide on bluebirdjs.com for the current package-manager steps.
Should I use bluebird or native promises?
The README says to use native promises if at all possible, since they have been stable in Node.js and browsers for years. Bluebird is only recommended for very old browsers, end-of-life Node.js, or as a debugging aid.
What are the alternatives to bluebird?
The comparable projects listed for this item are the native JavaScript Promise, Q, and RSVP.js. For most new projects, the README points to the native Promise as the first choice.
Where do I get help if something breaks?
Post usage questions on StackOverflow using the promise and bluebird tags. The GitHub issue tracker is reserved for bug reports and feature requests.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Bluebird suits maintainers of legacy codebases, projects that must support very old browsers or end-of-life Node.js, and developers who want its warnings to debug promises. If you are starting a new project on modern runtimes, the README recommends native promises instead, and you should pick one of the native-based options.
Install options & downloads