Installation on Heroku

Liu, An-Chi edited this page Feb 17, 2018 · 4 revisions

For the general set-up of a node.js app on Heroku's platform, see Heroku's Devcenter article on getting started.

Unfortunately, node-canvas doesn't work out of the box on Heroku because it needs the Cairo graphics library to be present in order to build. Cairo isn't installed on Heroku dynos by default.

You have two main options for deploying a node app that uses node-canvas to Heroku:

  • Use a custom buildpack for Heroku that installs Cairo for you
  • Use a fork of node-canvas that bundles pre-compiled libraries

With some fussing it is also possible to add Cairo binaries to your app's repository directly, but that isn't recommended.

Using a custom build pack

@mojodna has created a standalone Cairo buildpack intended for use with any other Heroku buildpacks (not just Node.js) through the magic of heroku-buildpack-multi (although at the time of this writing, you'll need to use the build-env branch of @mojodna's fork--track ddollar/heroku-buildpack-multi#18 for progress on this). It will install pre-compiled node-canvas dependencies (Cairo, Pixman, FreeType, and giflib) and will configure npm's build environment appropriately.

To use it, set your buildpack to heroku-buildpack-multi,, create a .buildpacks containing Cairo and Node.js buildpack URLs, and add node-canvas to your project and deploy as normal:

heroku config:add BUILDPACK_URL=

cat << EOF > .buildpacks

npm install --save canvas

git add .buildpacks package.json
git commit -m "node-canvas on Heroku"

git push heroku master

If you are struggling with this, go into your heroku app settings, scroll down to build backs and click "Add Buildpack" then add like so:

At the time of this writing (11/9/13), this is the most up-to-date method and is the only one known to support node-canvas-1.1.2.

Note: Stack heroku-16 is not supported. Use cedar-14.

Using a fork of node-canvas

Github user @elspoono has a fork of node-canvas that has been adapted for Heroku.

It is slightly out of date at the time of writing but it works well enough (with node-canvas <= 1.1.1). You need to reference this from your package.json file using the git URL because it's not published to npm. If you're developing locally you'll want to install the official version of canvas first. You can have the best of both worlds by putting the equivalent version of the original canvas lib in your devDependencies, which Heroku won't install:

  "dependencies": {
    "canvas": "git://"
  "devDependencies": {
    "canvas": "~0.8.1"

Possible issues

If something doesn't work, file an issue with the respective projects: mojodna/heroku-buildpack-cairo or elspoono/node-canvas-heroku.