Paper.js - The Swiss Army Knife of Vector Graphics Scripting

Prerequisites

• Node.js and npm: Required for installing and managing Paper.js packages
• Cairo Graphics Library (for canvas rendering): Required for paper-jsdom-canvas package
• Pango Library (for text rendering): Required for paper-jsdom-canvas package

Installation

Using npm

The recommended way to install Paper.js is through npm:

npm install paper

This will install the main paper package in your project's node_modules folder.

Available Packages

Paper.js is available in three different versions on npm:

• paper: Main library for browser, Node.js, or Electron
• paper-jsdom: Headless use with SVG importing/exporting through jsdom
• paper-jsdom-canvas: Canvas rendering through Node-Canvas plus SVG importing/exporting

Installing Native Dependencies

macOS

Install Cairo and Pango using Homebrew:

brew install cairo pango

If you encounter errors, set the PKG_CONFIG_PATH:

PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig/ npm install paper

For convenience, add this to your .bash_profile:

# PKG Config for Pango / Cairo
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig

Debian/Ubuntu Linux

sudo apt-get install pkg-config libcairo2-dev libpango1.0-dev libssl-dev libjpeg62-dev libgif-dev
sudo apt-get install build-essential

After Native Dependencies Installation

Once dependencies are installed, you can install the Paper.js module:

npm install paper

Configuration

Environment Variables

For macOS users with Cairo issues, set the PKG_CONFIG_PATH environment variable:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig

Package Selection

Choose the appropriate package based on your use case:

• Browser/Worker: Use paper package
• Headless Node.js: Use paper-jsdom package
• Node.js with Canvas: Use paper-jsdom-canvas package

Build & Run

In Browser

For browser usage, include the appropriate distribution:

• paper-full.js: Full version with PaperScript support and Acorn.js
• paper-core.js: Core version without PaperScript support or Acorn.js

In Node.js

// For basic usage
const paper = require('paper');

// For jsdom (headless)
const paper = require('paper-jsdom');

// For canvas rendering
const paper = require('paper-jsdom-canvas');

Example Usage

// Create a circle
const circle = new paper.Path.Circle({
    center: [50, 50],
    radius: 30
});
circle.fillColor = 'red';

Deployment

Paper.js is designed for web applications and can be deployed on any platform that supports JavaScript:

• Static hosting: Netlify, Vercel, GitHub Pages
• Node.js applications: Heroku, Railway, AWS Lambda
• Electron applications: Desktop apps using the paper package
• Web workers: For background processing in browsers

For production deployments, use the minified versions (paper-full.min.js or paper-core.min.js) to reduce file size.

Troubleshooting

Common Issues

1. Cairo/Pango installation errors on macOS:

   • Set PKG_CONFIG_PATH: PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig/ npm install paper
   • Add to .bash_profile for persistent configuration

2. Module not found errors:

   • Ensure you've run npm install paper
   • Check that you're requiring the correct package for your use case

3. Canvas rendering issues in Node.js:

   • Verify Cairo and Pango are properly installed
   • Use paper-jsdom-canvas package for canvas support

4. SVG import/export issues:

   • Use paper-jsdom or paper-jsdom-canvas packages
   • Ensure jsdom is properly configured

Getting Help

• Documentation: http://paperjs.org/
• Questions: Stack Overflow
• Discussion: Google Groups
• Issues: GitHub Issues