DOCSEARCHbyAlgolia
Submit Docs

Paper.js Vector Graphics Scripting Framework

repository·develop·Indexed 12 days ago

https://github.com/paperjs/paper.js

A vector graphics scripting framework for high-level manipulation of vector graphics in browsers and Node.js. Version 0.12.18 provides a core library for web environments and specialized NPM packages like paper-jsdom and paper-jsdom-canvas for headless SVG and Canvas rendering in Node.js. It offers two browser distribution variants: paper-full.js, which includes PaperScript and Acorn.js, and paper-core.js for standard JavaScript usage.

Tokens
2K
Snippets
15
Records
19
Agent score
95%

What's inside Paper.js

  1. Use Paper.js in headless Node.js environments with paper-jsdom

    develop
    The paper-jsdom package allows you to use Paper.js in headless Node.js environments. It enables vector graphics scripting without a browser by using jsdom to simulate the DOM. This package specifically supports SVG importing and exporting within Node.js.

  2. Use Paper.js in Node.js with Canvas and JSDOM

    develop
    The paper-jsdom-canvas package allows you to run Paper.js in a Node.js environment. It provides vector graphics capabilities by using jsdom for DOM simulation (enabling SVG import/export) and node-canvas for canvas-based rendering. This is ideal for server-side vector graphics generation or headless browser-like environments.

  3. Understand Paper.js distribution variants

    develop

    When using Paper.js in the browser, you can choose between two pre-built variants:

    • paper-full.js: The complete version, including PaperScript support and Acorn.js.
    • paper-core.js: The core version without PaperScript or Acorn.js. Use this to reduce bundle size and compilation time if you are working directly with standard JavaScript.

  4. Choose the correct Paper.js NPM package

    develop

    Paper.js provides three distinct packages on NPM depending on your runtime environment:

    • paper: The main library for browser environments (web browsers or web workers).
    • paper-jsdom: A shim for Node.js that provides headless support with SVG import/export via jsdom.
    • paper-jsdom-canvas: A shim for Node.js that provides both jsdom SVG support and Canvas rendering via Node-Canvas.

    Note: To use paper-jsdom-canvas, you must have the Cairo Graphics library installed on your system.

  6. Run Paper.js directly from source files

    develop

    For rapid development without rebuilding the entire library after every change, use the load task. This replaces the built libraries in dist with symbolic links to src/load.js, which uses Prepro.js to load source files directly. This works for both browsers and Node.js.

    To switch back to the built library, run yarn build.

    yarn load
# To revert to built files:
yarn build

  7. Run Paper.js tests

    develop

    Paper.js uses Qunit for unit testing. You can run tests in different environments using the following commands:

    • Browser (Chrome/Local Server): Use yarn test:browser to start a local web server to bypass CORS restrictions.
    • PhantomJS: Use yarn test:phantom for command-line testing.
    • Node.js: Use yarn test:node to test the Node.js version.
    • Combined: Use yarn test to run both PhantomJS and Node.js tests together.
    yarn test:browser
yarn test:phantom
yarn test:node
yarn test

  8. Install Paper.js via NPM

    develop

    The recommended way to install Paper.js for browsers, Node.js, or Electron is using NPM. Run the following command in your project folder to install the main library:

    npm install paper

    This will create a paper folder inside your node_modules directory.

  9. Install native dependencies for paper-jsdom-canvas on Debian/Ubuntu

    develop

    To install the necessary native libraries for Node-Canvas on Debian or Ubuntu, run:

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

    You may also need build-essential if you do not typically build from C++ sources:

    sudo apt-get install build-essential

  10. Install paper-jsdom-canvas after native dependencies

    develop

    Once the native dependencies (Cairo and Pango) are installed on your system, you can install the Paper.js module for Node.js with Canvas rendering via NPM:

    npm install paper-jsdom-canvas

  12. Install native dependencies for paper-jsdom-canvas on macOS

    develop

    Since paper-jsdom-canvas relies on Node-Canvas, which requires Cairo and Pango, you should install them using Homebrew:

    brew install cairo pango

    If you encounter errors during installation on macOS, you may need to explicitly set the PKG_CONFIG_PATH to point to your X11 installation:

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

    To avoid setting this every time, you can add the following to your .bash_profile:

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