canvas-sketch

:closed_book: canvas-sketch → Documentation → Installation

Installation

The recommended way to use canvas-sketch and its tooling is with its command-line interface. This will run a local development server that handles browser reload on file save, high-quality PNG exporting, and other features.

Requirements:

If you don’t have these tools, or would rather not use them, see the following:

How to Install the CLI

You can choose between three ways to install and use the CLI tool:

Option 1: Quick-Start with npx

A simple way to use the tool is with npx which comes built-in to npm. Run it like this:

# Make a new folder to hold all your generative sketches
mkdir my-sketches

# Move into that folder
cd my-sketches

# Scaffold a new sketch file and open the browser
npx canvas-sketch-cli --new --open

:bulb: Using npx, instead of the canvas-sketch command, you will use npx canvas-sketch-cli (notice the -cli suffix).

The above command does a few things:

It also launches your default browser to http://localhost:9966/ (the development server), showing a blank white canvas:

Now you can edit the newly created JavaScript file in the sketches/ folder. When you save changes, the browser will reload immediately.

For example, try changing the 'white' fill style to 'red'.

const canvasSketch = require("canvas-sketch");

const settings = {
  dimensions: [2048, 2048],
};

const sketch = () => {
  return ({ context, width, height }) => {
    context.fillStyle = "red"; // <-- Try changing the color
    context.fillRect(0, 0, width, height);
  };
};

canvasSketch(sketch, settings);

Option 2: Installing the CLI Globally (--global)

You might want to install the CLI tool globally, so that you can just type canvas-sketch into your terminal. This is the command that a lot of the documentation will assume.

You can use the following to install it globally:

npm install canvas-sketch-cli --global

:bulb: If you run into errors, see Troubleshooting.

After installing, you may need to quit and re-open your terminal app.

Example usage:

# Make a new folder to hold all your sketches
mkdir my-sketches

# Move into that folder
cd my-sketches

# Start a new sketch and open the browser
canvas-sketch sketch.js --new --open

Option 3: Installing the CLI Locally (--save-dev)

If you prefer not to install your CLI tools globally, you can install the CLI locally in each project that you need it by saving it as a devDependency:

npm install canvas-sketch-cli --save-dev

Now, to run it in each project, you can add canvas-sketch commands to your npm run scripts, or use npx which will try to run the locally-installed version first:

npx canvas-sketch my-sketch.js --open

:bulb: If you’ve installed canvas-sketch-cli locally, you can then use npx to run the command in that project folder without needing to include the -cli suffix.

More Tips

💾 Exporting as PNG

In the browser, hit Cmd + S or Ctrl + S to export your canvas as a PNG file. It will be saved to your ~/Downloads folder (and similar across other platforms).

:bulb: A Few More Examples to Try

Now that you’ve got it running, you could try out a few different commands:

# Run the development server on an existing file
canvas-sketch src/foobar.js

# Start a new sketch from the Three.js template
canvas-sketch --new --template=three --open

# Build your sketch to a sharable HTML + JS website
canvas-sketch sketches/my-sketch.js --build

# Paste the clipboard contents & run a new sketch at './foo.js'
pbpaste | canvas-sketch foo.js --new

Updating

There are two separate packages, so you might need to update them separately:

Updating canvas-sketch (JavaScript API and Library)

When you run canvas-sketch-cli in a folder, it will often install the library locally as a dependency in your package.json for that folder. To update this, you can re-install the library (not the CLI) locally in each project folder that uses it:

npm install canvas-sketch@latest

1. Updating the CLI using the Quick-Start npx

If you’re just using npx Quick-Start, you will need to clear the npx cache. Run the following:

npx clear-npx-cache@1.0.1

Then you can re-run your command with npx and it will pick up the latest version, such as:

npx canvas-sketch-cli sketch.js

2. Updating a Globally Installed CLI (--global)

If you’ve previously installed the tool globally (Option 2), you can update it just by re-installing:

npm install canvas-sketch-cli@latest --global

3. Updating a Locally Installed CLI (--save-dev)

If you’ve previously installed the tool locally (Option 3), you can update it just by re-installing:

npm install canvas-sketch-cli@latest --save-dev

##

Now that you’re set up, you might like to read A “Hello, World” Sketch.

← Back to Documentation

This site is open source. Improve this page.