If you want to work with Paper.js, simply download the latest "stable" version from http://paperjs.org/download/
- Website: http://paperjs.org/
- Discussion forum: http://groups.google.com/group/paperjs
- Mainline source code: https://github.com/paperjs/paper.js
- Twitter: @paperjs
- Latest releases: http://paperjs.org/download/
- Pre-built development versions:
The recommended way to install and maintain Paper.js as a dependency in your project is through NPM or Bower for browsers, and through NPM for Node.js.
If NPM or Bower is already installed, simply type one of these commands in your project folder:
npm install paper
bower install paper
Upon execution, you will find a
paper folder inside the project's
For more information on how to install NPM and Bower, read the chapter Installing Node.js, NPM and Bower.
To learn more about its features for dependence tracking, see http://bower.io/.
Which Version to Use?
The various distributions come with two different pre-build versions of Paper.js, in minified and normal variants:
paper-full.js– The full version for the browser, including PaperScript support and Acorn.js
Installing Node.js, NPM and Bower
Node.js is required by Bower, as well as by Gulp.js, which needs to be installed if you intend to build the library or its documentation by yourself.
There are many tutorials explaining the different ways to install Node.js on different platforms. It is generally not recommended to install Node.js through OS-supplied package managers, as the its development cycles move fast and these versions are often out-of-date.
NVM can be used instead to install and maintain multiple versions of Node.js on the same platform, as often required by different projects: http://blog.dynamicprogrammer.com/2014/02/18/installing-node-js-on-mac-osx.html
on OSX, Homebrew is also a good option if one version of Node.js on the platform is enough: http://blog.teamtreehouse.com/install-node-js-npm-mac
Homebrew is recommended on OSX also if you intend to install Paper.js for Node.js, as described in the next paragraph.
Once Node.js (with NPM) has been installed you can install bower globally using the following command:
npm install -g bower
And from there onwards, you should be able to use Bower like this:
bower search paperjs
Installing Paper.js for Node.js through NPM
NPM is used to install Paper.js for use in Node.js. But before installing, you need the Cairo Graphics library installed, see: http://cairographics.org/.
Installing Cairo and Pango on OSX:
The easiest way to install Cairo is install Homebrew http://mxcl.github.io/homebrew/ then issue the command:
brew install cairo pango
Note that currently there is an issue on OSX with Cairo. If the above causes errors, the following will most likely fix it:
PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig/ npm install paper
Also, whenever you would like to update the modules, you will need to execute:
PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig/ npm update
If you keep forgetting about this requirement, or would like to be able to type simple and clean commands, add this to your
# PKG Config for Pango / Cairo export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig
After adding this line, your commands should work in the expected way:
npm install paper npm update
Installing Cairo, Pango and all other dependencies on Debian/Ubuntu Linux:
sudo apt-get install pkg-config libcairo2-dev libpango1.0-dev libssl-dev libjpeg62-dev libgif-dev
You might also need to install the build-essential package if you don't usually build from c++ sources:
sudo apt-get install build-essential
After Cairo has been installed:
You should now be able to install the Paper.js module from NPM:
npm install paper
The main Paper.js source tree is hosted on GitHub.
git is required to create a clone of the repository, and can be easily installed through your preferred package manager on your platform.
Get the Source
git clone --recursive git://github.com/paperjs/paper.js.git cd paper.js
To refresh your clone and fetch changes from origin, run:
git fetch origin
To update the
jsdoc-toolkit submodule, used to generate the documentation, run:
git submodule update --init --recursive
Setting Up For Building
In order to be able to build Paper.js, after checking out the repository, paper has dependencies that need to be installed. Install them by issuing the following commands from the Paper.js directory:
It is also recommended to install Gulp.js globally, so you can easier execute the build commands from anywhere in the command line:
npm install -g gulp
Building the Library
The Paper.js sources are distributed across many separate files, organised in subfolders inside the
src folder. To compile them all into distributable files, you can run the
You will then find the built library files inside the
dist folder, named
paper-core.js, along with their minified versions. Read more about this in Which Version to Use?.
Running Directly from Separate Source Files
As a handy alternative to building the library after each change to try it out in your scripts, there is the
load task, that replaces the built libraries with symbolic links to the
scrc/load.js script. This script then load the library directly from all the separate source files in the
This means you can switch between loading from sources and loading a built library simply by running.
And to go back to a built library
Note that your PaperScripts examples do not need to change, they can keep loading
dist/paper-full.js, which will always do the right thing. Note also that
src/load.js handles both browsers and Node.js, as supported by Prepro.js.
Other Build Tasks
Create a final zipped distribution file inside the
dist is the default task, this is the same:
Since the release of version
0.9.22, Paper.js has adopted aspects of the Git- Flow workflow. All development is taking place in the
develop branch, which is only merged into
master when a new release occurs.
As of version
dist folder is excluded on all branches, and the building is now part of the
npm publish process by way of the
Building the Documentation
Similarly to building the library, you can run the
docs task to build the documentation:
Your docs will then be located at
Paper.js was developed and tested from day 1 using proper unit testing through jQuery's Qunit. To run the tests after any change to the library's source, simply open
index.html inside the
test folder in your web browser. There should be a green bar at the top, meaning all tests have passed. If the bar is red, some tests have not passed. These will be highlighted and become visible when scrolling down.
If you are testing on Chrome, some of the tests will fail due to the browser's CORS restrictions. In order to run the browser based tests on Chrome, you need to run a local web-server through Gulp.js. The following command will handle it for you, and will also open the browser at the right address straight away:
You can also run the unit tests through PhantomJS in Gulp directly on the command line:
To test the Node.js version of Paper.js, use this command:
And to test both the PhantomJS and Node.js environments together, simply run:
The main Paper.js source tree is hosted on GitHub, thus you should create a fork of the repository in which you perform development. See http://help.github.com/forking/.
We prefer that you send a pull request on GitHub which will then be merged into the official main line repository. You need to sign the Paper.js CLA to be able to contribute (see below).
Also, in your first contribution, add yourself to the end of
AUTHORS.md (which of course is optional).
Get the source (for contributing):
If you want to contribute to the project you will have to make a fork. Then do this:
git clone --recursive firstname.lastname@example.org:yourusername/paper.js.git cd paper.js git remote add upstream git://github.com/paperjs/paper.js.git
To then fetch changes from upstream, run
git fetch upstream
Creating and Submitting a Patch
As mentioned above, we prefer that you send a pull request on GitHub:
Clone of your repository:
git clone https://email@example.com/yourusername/paper.js.git
This is important: Create a so-called topic branch based on the
git checkout -tb name-of-my-patch developwhere
name-of-my-patchis a short but descriptive name of the patch you're about to create. Don't worry about the perfect name though -- you can change this name at any time later on.
Hack! Make your changes, additions, etc., commit them then push them to your GitHub fork:
git push origin name-of-my-patch
Send a pull request to the upstream repository's owner by visiting your repository's site at GitHub (i.e. https://github.com/yourusername/paper.js) and press the "Pull Request" button. Make sure you are creating the pull request to the
developbranch, not the
masterbranch. Here's a good guide on pull requests: http://help.github.com/pull-requests/
Use one topic branch per feature:
Don't mix different kinds of patches in the same branch. Instead, merge them all together into your
develop branch (or develop everything in your
develop branch and then cherry-pick-and-merge into the different topic branches). Git provides for an extremely flexible workflow, which in many ways causes more confusion than it helps you when new to collaborative software development. The guides provided by GitHub at http://help.github.com/ are a really good starting point and reference. If you are fixing an issue, a convenient way to name the branch is to use the issue number as a prefix, like this:
git checkout -tb issue-937-feature-add-text-styling.
Contributor License Agreement
Before we can accept any contributions to Paper.js, you need to sign this CLA:
The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to Paper.js and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time.
For a list of authors and contributors, please see AUTHORS.
Distributed under the MIT license. See LICENSE for details.