Skip to content

Installation: Heroku

Jump to bottom
Zach Bjornson edited this page Jul 7, 2018 · 1 revision

Canvas 2.0 and 1.6 works out-of-the-box on the heroku-16 stack thanks to prebuilds.

The info below pertains to older versions that don't have a prebuild available, or attempting to build canvas from source.

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=https://github.com/mojodna/heroku-buildpack-multi.git#build-env

cat << EOF > .buildpacks
https://github.com/mojodna/heroku-buildpack-cairo.git
https://github.com/heroku/heroku-buildpack-nodejs.git
EOF

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 https://github.com/mojodna/heroku-buildpack-cairo.git 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.

Clone this wiki locally