p5-server

Create and run p5.js sketches, explore sketch collections. Includes a sketch-aware development server with live reload; a sketch explorer; and support for JavaScript-only sketches with automatic library inclusion.

• Features
  • Sketch Explorer
  • Integrated Web Server
  • Integrated Browser
  • Browser Debugging
  • Integrated Console
  • Automatic Library Includes
  • Other Features
• Installation
• Step by Step
• Configuration
• Limitations
• Related Projects
• Development
• Keeping in Touch
• Acknowledgements
• License

Features

Sketch Explorer

The Sketch Explorer is similar to Visual Studio Code's built-in Explorer, but the Sketch Explorer is organized around sketches instead of files. It supports both sketches that are included in HTML files, and JavaScript-only sketches (that don't have an HTML file).

The extension finishes loading after VS Code starts so the P5 Server status item remains immediately available. The server and its browser-console relay still load only when a sketch is run.

Clicking on a sketch in the Sketch Explorer opens its JavaScript file in the Visual Studio Code editor.

Integrated Web Server

The extension includes a local web server. This server reloads sketches when files are modified. It also serves JavaScript-only sketches in a way that the browser can play.

Integrated Browser

The Run Sketch command can open the sketch in an external web browser (such as Chrome, Safari, or Edge), or in VS Code's integrated browser. (The "P5-server: Browser" setting controls this.) The integrated route uses the current built-in browser when available and falls back to Simple Browser on compatible older builds.

If the "P5-server > Explorer: Auto Run Sketch On Side" setting is enabled, clicking on a sketch in the Sketch Explorer also runs it next to the editor. This makes it easy to quickly browse a collection of sketches.

Browser Debugging

Debug P5 Sketch starts the server if necessary and launches VS Code's browser debugger. Breakpoints, stepping, variables, the Debug Console, and the usual debug controls work without creating a launch.json file. The command is available from the editor title, Command Palette, and Sketch Explorer.

Integrated Console

When the "P5-server: Browser" setting is set to integrated, messages from console.log() and other console output will display in the P5 Sketch log output. These messages also appear as inlay hints in the JavaScript source file. Runtime exceptions appear in VS Code's Problems view and at the failing source location.

The console output pane automatically appears when a message is printed to it. This behavior can be changed via the "Console > Integrated Browser > Auto Show: Level" setting.

High-volume output is batched to keep the editor responsive. Inline messages are coalesced and retain a bounded recent history. Turning off the Editor > Info Lens setting removes the extension's inlay hints and diagnostics; output-channel logging continues.

Automatic Library Includes

If a JavaScript-only sketch uses a class or function from one of the p5.js community libraries, or from my own library collection, that library is automatically included.

In the screenshot below, the extension infers that the sound.js sketch requires the p5.sound library, because of the presence of a call to loadSound(). Running the sketch will include this library.

The explorer also detects that the file doorbell.mp3 is associated with the sketch, because it's the argument to the p5.js function loadSound().

Other Features

• JavaScript-Only Sketches. A sketch can be a single JavaScript file. (No HTML is necessary.)
• In-Page syntax errors. If a JavaScript file has a syntax error, it is displayed in the body of the page (you don't have to check the console).
• P5-aware directory listings. Viewing a directory in the browser lists the sketches, folders, other files in that directory.
• Sketch scripts generation. Create a JavaScript-only sketch that contains a minimal setup() and draw() function; or create a pair of index.html and sketch.js.
• Remote workspaces. The workspace extension runs with Remote SSH, Dev Containers, WSL, and Codespaces-style hosts. Browser URLs are forwarded through VS Code before they open on the local machine.
• Safe file operations. Deleted sketches go to the operating system trash, and renames participate in VS Code's workspace-edit flow.

Installation

View the Visual Studio Code Marketplace extension page, and click the Install button.

P5 Server requires Visual Studio Code 1.115 or newer. After installation, open Help: Get Started and select Get Started with P5 Server for an in-editor walkthrough.

Step by Step

Step-by-step installation and usage instructions are here.

Configuration

The extension provides configuration settings to set the browser, and to hide various user interface elements. Follow these instructions to modify these settings.

Limitations

See the p5-server documentation for limitations that also affect this extension.

In particular:

• The extension has not been tested on Windows.
• Virtual workspaces that do not expose an extension-host filesystem path are not supported. Remote workspace folders with filesystem paths are supported.
• In Restricted Mode, the Sketch Explorer and file-management commands remain available, but starting, running, and debugging sketches require workspace trust because they execute workspace JavaScript in a browser.
• The sketches that are created by the “Create p5.js Sketch Folder” command require an internet connection to run. (They load the p5.js and other libraries from a content delivery network, or “CDN”.) Browsers cache these files, so reloading a page or running other sketches that use the same libraries does not require additional internet access, but you will need internet access the first time you use this extension or after the browser cache has expired.
• Similarly, the server requires an internet connection the first time it displays a sketch or directory listing. (Remote assets are cached, so it does not need a connection to display a second sketch or a second directory listing.)

Related Projects

The sketch-aware server is available as command-line tool at p5-server. Install it via npm install -g p5-server, and run p5 serve or p5 serve --template split.

The command-line version can also be used to generate a static web site. This creates the HTML files that are necessary to run the sketch in a browser without a special server.

The code to infer libraries from JavaScript-only sketches, and to generate HTML files based on this, is available as a separate package.

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

Development

For information on developing and contributing to this extension, please see DEVELOPMENT.md.

Keeping in Touch

Bug reports, suggestions, and other contributions are cheerfully accepted. Please use the Issues page of the GitHub repository.

Acknowledgements

• The functionality and user interface of this extension were heavily inspired by Ritwick Dey's fantastic Live Server extension. My own extension (p5 server) does more for p5.js sketches, but it does not implement Live Server's extensive list of features for general web development.
• The open package is used to open URL's in various browsers.
• I learned a lot from reading the source code to the Alessandro Fragnani's vscode-project-manager extension. (I use this extension and his Bookmarks extension in my own VSCode configuration.)
• The What's New page uses the HTML structure and the CSS from the GitHub Desktop web site.
• Thanks to GitHub users @munusshih, @xuzheng465, @ronyginosar, @lorenzo-leuck, and @pwalsh for reporting bugs and helping improve the extension.

License

MIT by Oliver Steele