P5.js Server

npm version

Overview

p5-server is a command-line interface for p5.js. It provides a web server with live reload, that knows how to serve JavaScript-only sketches and to figure out which libraries a sketch needs in order to run.

Directory listing in the browser

You can use it develop sketches, or to browse a collection of sketches in a directory.

Using the split view to explore a collection of sketches. Click to see a higher-resolution version.

p5-server can also be used to create a set of HTML pages that present a collection of sketches. The examples page of the p5.vectorArguments documentation demonstrates this.

The web server, library inference, and sketch generation features are also available as a Visual Studio Code extension, and via a programmatic API.

Features

Quick Start – Installation

These commands install the p5 command on your computer. You only need to do them once.

Text shown in monospace should be entered into a terminal.

  1. node --version

    This tests whether Node.js is installed on your system. It should print something like v16.9.0. (The exact number doesn’t matter; you just want it not to report an error such as “command not found”.)

    If Node.js is not installed, install it from here. It doesn’t matter whether you install the LTS or Current version of node.

  2. npm install -g p5-server

    This installs the p5 command on your computer.

    Once this is done, you can enter commands such as p5 create and p5 serve, or just p5 to see a list of all the commands.

Quick Start – Usage

  1. p5 create my-sketch

    This creates a sketch named my-sketch.js in the current directory.

    If you already have some sketches on your file system, you can skip this step. Instead, use the cd command to change the terminal’s current directory to a directory that contains some sketches.

  2. p5 serve --open

    This starts the server, and opens your sketch directory in the browser.

    Click on a sketch in the browser page to run it.

  3. Use a code editor (such as Atom, Visual Studio Code, vim, or emacs) to edit the my-sketch.js file that you created in step 1. Each time you save the file, the browser will reload the page and re-run your sketch.

Recipes

Run the Server

p5 server

Starts a web server that knows about p5.js sketches, and that reloads sketches when files are changed. The server is set to serve files from the current directory.

Serve a directory inside the current directory

p5 server PATH

Starts a server that serves files from the directory at PATH.

Open the browser automatically

p5 server --open

Starts the server, and opens the directory in the default browser.

Browse directories in split mode

p5 server --split

Displays directory listings with the sketch in the same window (inside of an iframe), as shown in the screen shot above.

You can combine options, e.g. p5 server examples --open --split.

Create a sketch file

The default generated script contains setup() and draw() functions. The setup() functions creates a canvas, and the draw() functions draws circles that follow the mouse. --options can be used to customize this script. See the reference, below.

Build a static site

p5 build SOURCES builds a static site into ./build.

Run p5 build --help for a list of options.

Two themes are supported, --theme directory and --theme split.

Create a screenshot

p5 screenshot my-sketch.js creates a screenshot named my-sketch.png in the current directory. It operates by running the sketch in a browser, saving the canvas, and then closing the browser page.

You can also use p5 screenshot my-sketch.html for an HTML sketch; and p5 screenshot dir where dir names a single-sketch directory.

Run p5 screenshot --help for a list of options. There are options to set the output filename, the number of the starting frame, the pixel density, the canvas dimensions, and the browser (Safari, Chrome, Firefox, or Edge).

Notes:

Convert between JavaScript-only and HTML sketches

p5 convert sketch.html converts an HTML sketch to a JavaScript-only sketch, by deleting the HTML file. It first inspects this file, to insure that the sketch contains only a single script file, and that all the information necessary to run the sketch is in the script.

p5 convert sketch.js creates an HTML file that can be used to run the sketch.

Command-Line Reference

Run p5 --help to see a list of commands.

Run p5 <command> --help to see command-line options for a particular command.

p5 build [DIRECTORY]

p5 convert FILENAME --to FORMAT

Converts between HTML and JavaScript-only sketches.

Converting a JavaScript-only sketch is simple. An HTML file with the same base name is created, that includes the script, the p5.js source (from a CDN), and any inferred libraries. This will fail if the directory already contains a HTML file with this name.

Converting an HTML sketch to a JavaScript-only sketch involves deleting the HTML file that includes the script. This potentially looses some information. Before the file is deleted, the following checks are made:

p5 create [NAME]

Create a JavaScript-only sketch; or an HTML file and a JavaScript file.

p5 create --options comments,preload specifies a comma-separated set of template options. The options are:

p5 serve [filename]

Runs a web server that knows about p5.js sketches.

or the filename subdirectory of the current directory.

p5 serve filename runs a sketch in the browser.

By default, the server runs on port 3000. You can open it in a browser by visiting http://localhost:3000. The p5 server --open will do this automatically.

If another server is already running on port 3000, the server will choose another port.

p5 sceenshot [filename]

Open the sketch in a browser, and save the canvas as an image.

p5 tree [DIRECTORY]

Display the contents of DIRECTORY, organized by sketch.

$ yarn cli tree examples
📁examples
├── 🎨circles (circles.js)
├── 🎨sketch
│   ├── sketch.html
│   ├── main.js
│   └── helper.js
├── 🎨sketch-dir
│   ├── index.html
│   └── sketch.js
├── 🎨squares (squares.js)
├── 🎨syntax-error
│   ├── index.html
│   └── sketch.js
├── 📁collection
│   ├── 🎨sketch 1 (sketch-1.js)
│   ├── 🎨sketch 2 (sketch-2.js)
│   └── README.md
├── 📁libraries
│   ├── 🎨dat.gui (dat.gui.js)
│   ├── 🎨layers (layers.js)
│   ├── 🎨posenet (posenet.js)
│   ├── 🎨sound
│   │   ├── sound.js
│   │   └── doorbell.mp3
│   ├── 🎨sound pulse (sound-pulse.js)
│   ├── 🎨vector arguments (vector-arguments.js)
│   └── README.md
└── README.md

This is similar to what the Sketch Explorer view in the Visual Studio Code extension displays.

Implementation Notes

The p5-analysis implementation notes describe sketch detection, automatic library inclusion, and other details of the implementation.

Limitations

API

The server can be invoked programmatically. See the API Reference for installation instructions and reference documentation for this use.

Acknowledgements

This project builds on these libraries and frameworks:

Other Work

https://code.osteele.com lists my other p5.js projects. These include tools, libraries, and examples and educational materials.

Keeping in Touch

Report bugs, features requests, and suggestions here, or message me on Twitter.

Follow [@osteele on Twitter](https://twitter.com/osteele) for updates.

License

MIT © by Oliver Steele