{"id":16508526,"url":"https://github.com/osteele/p5-server","last_synced_at":"2025-08-07T16:12:16.700Z","repository":{"id":57156931,"uuid":"388727825","full_name":"osteele/p5-server","owner":"osteele","description":"Command-line tool to create and run p5.js sketches. It runs a server with live reload, sketch-aware directory listings, automatic libraries for JavaScript-only sketches.","archived":false,"fork":false,"pushed_at":"2025-04-25T21:56:03.000Z","size":18720,"stargazers_count":50,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-22T00:53:01.574Z","etag":null,"topics":["live-reload","p5","p5js"],"latest_commit_sha":null,"homepage":"https://osteele.github.io/p5-server/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osteele.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-23T08:14:13.000Z","updated_at":"2025-05-24T11:28:10.000Z","dependencies_parsed_at":"2024-06-21T20:19:20.684Z","dependency_job_id":"57035c70-b3ee-4666-bd98-b18d4cb3c63a","html_url":"https://github.com/osteele/p5-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/osteele/p5-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fp5-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fp5-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fp5-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fp5-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osteele","download_url":"https://codeload.github.com/osteele/p5-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fp5-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269286157,"owners_count":24391406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["live-reload","p5","p5js"],"created_at":"2024-10-11T15:46:01.219Z","updated_at":"2025-08-07T16:12:16.680Z","avatar_url":"https://github.com/osteele.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# P5.js Server\n\n[![npm version](https://badge.fury.io/js/p5-server.svg)](https://www.npmjs.com/package/p5-server)\n\u003c!-- [![CI workflow](https://github.com/osteele/p5-server/actions/workflows/ci.yml/badge.svg)](https://github.com/osteele/p5-server/actions/workflows/ci.yml) --\u003e\n\n- [Overview](#overview)\n- [Features](#features)\n- [Quick Start – Installation](#quick-start--installation)\n- [Quick Start – Usage](#quick-start--usage)\n- [Recipes](#recipes)\n  - [Run the Server](#run-the-server)\n    - [Serve a directory inside the current directory](#serve-a-directory-inside-the-current-directory)\n    - [Open the browser automatically](#open-the-browser-automatically)\n    - [Browse directories in split mode](#browse-directories-in-split-mode)\n    - [Create a sketch file](#create-a-sketch-file)\n  - [Build a static site](#build-a-static-site)\n  - [Create a screenshot](#create-a-screenshot)\n  - [Convert between JavaScript-only and HTML sketches](#convert-between-javascript-only-and-html-sketches)\n- [Command-Line Reference](#command-line-reference)\n  - [`p5 build [DIRECTORY]`](#p5-build-directory)\n  - [`p5 convert FILENAME --to FORMAT`](#p5-convert-filename---to-format)\n  - [`p5 create [NAME]`](#p5-create-name)\n  - [`p5 serve [filename]`](#p5-serve-filename)\n  - [`p5 screenshot [filename]`](#p5-screenshot-filename)\n  - [`p5 tree [DIRECTORY]`](#p5-tree-directory)\n  - [Additional commands](#additional-commands)\n- [Implementation Notes](#implementation-notes)\n- [Limitations](#limitations)\n- [API](#api)\n- [Acknowledgements](#acknowledgements)\n- [Other Work](#other-work)\n- [Keeping in Touch](#keeping-in-touch)\n- [License](#license)\n\n## Overview\n\n**New feature: “airplane mode”. The server caches requests to known CDN servers,\nso that you can run sketches without an internet connection. See\n[here](docs/proxy-cache.md) for more details.**\n\n**p5-server** is a development server for [p5.js](https://p5js.org/). It\nprovides a web server with live reload, and command-line tools to generate HTML\nand JavaScript templates. The server can serve JavaScript-only sketches (that do\nnot require an HTML file); it figures out which libraries a sketch needs in\norder to run.\n\n![Directory listing in the browser](docs/screenshot.png)\n\np5-server can be used to develop sketches; or to browse a collection of sketches\nin a directory.\n\n[![Using the split view to explore a collection of sketches. Click to see a higher-resolution version.](docs/explore.gif)](https://images.osteele.com/p5-server/explore-fullsize.gif)\n\np5-server can also be used to create a set of HTML pages that present a\ncollection of sketches. The [examples\npage](https://osteele.github.io/p5.libs/p5.vector-arguments/examples) of the\n[p5.vectorArguments](https://osteele.github.io/p5.libs/p5.vector-arguments)\ndocumentation demonstrates this.\n\nThe web server, automatic library inclusion, and sketch generation features are\nalso available as a [Visual Studio Code\nextension](https://github.com/osteele/vscode-p5server#readme), and via a\n[programmatic\nAPI](https://github.com/osteele/p5-server/tree/master/p5-analysis#readme).\n\n## Features\n\n- ***Live reload***. The browser reloads the page when the source is\n  modified.\n- ***JavaScript-only sketches***. A sketch can be a single JavaScript file. You\n  don't need to create an HTML file just to run the sketch.\n- ***Automatic includes***. If a JavaScript-only sketch uses a function\n  from [one of these\n  libraries](https://osteele.github.io/p5-server/p5-analysis/libraries), the\n  library will be included. ([This\n  page](https://github.com/osteele/p5-server/tree/master/p5-analysis#automatic-library-inclusion)\n  describes how this works.)\n- ***In-browser syntax errors***. A JavaScript file that has a syntax error will\n  display the error in the browser. Edit and save the file to reload the page.\n\n    ![Syntax error reported in browser](docs/syntax-error.png)\n    ![Syntax error reported in browser split-view](docs/syntax-error-split.png)\n- ***Sketch-aware directory listings***. Viewing a directory in the browser\n  lists the sketches, folders, other files in that directory.\n- ***Sketch file generation***. `p5 generate` creates a sketch file that you can\n  use to get started.\n- **Integrated web accelerator (CDN Cache)**. The server proxies requests to the\n  common content delivery networks (CDNs) that are used to deliver the sources\n  to p5.js and common p5.js libraries. See [here](./docs/proxy-cache.md) for\n  more information about how this works.\n\n## Quick Start – Installation\n\nThese commands install the `p5` command on your computer. You only need to do\nthem once.\n\nText shown in `monospace` should be entered into a terminal.\n\n1. `node --version`\n\n   This tests whether Node.js is installed on your system. It should print\n   something like `v16.9.0`. (The exact number doesn't matter; you just want it\n   not to report an error such as \"command not found\".)\n\n   If Node.js is *not* installed, install it from [here](https://nodejs.org/).\n   It doesn't matter whether you install the LTS or Current version of node.\n\n2. `npm install -g p5-server`\n\n    This installs the `p5` command on your computer.\n\n    Once this is done, you can enter commands such as `p5 create` and `p5\n    serve`, or just `p5` to see a list of all the commands.\n\n## Quick Start – Usage\n\n1. `p5 create my-sketch`\n\n    This creates a sketch named `my-sketch.js` in the current directory.\n\n    If you already have some sketches on your file system, you can skip this\n    step. Instead, use the `cd` command to change the terminal's current\n    directory to a directory that contains some sketches.\n\n2. `p5 serve --open`\n\n   This starts the server, and opens your sketch directory in the browser.\n\n   Click on a sketch in the browser page to run it.\n\n3. Use a code editor (such as [Atom](https://atom.io), [Visual Studio\n   Code](https://code.visualstudio.com), vim, or emacs) to edit the\n   `my-sketch.js` file that you created in step 1. Each time you save the file,\n   the browser will reload the page and re-run your sketch.\n\n## Recipes\n\n### Run the Server\n\n`p5 server`\n\nStarts a web server that knows about p5.js sketches, and that reloads\nsketches when files are changed. The server is set to serve files from the\ncurrent directory.\n\n#### Serve a directory inside the current directory\n\n`p5 server PATH`\n\nStarts a server that serves files from the directory at *PATH*.\n\n#### Open the browser automatically\n\n`p5 server --open`\n\nStarts the server, and opens the directory in the default browser.\n\n#### Browse directories in split mode\n\n`p5 server --theme grid`\n\nDisplays directory listings in grid view.\n\nYou can combine options, e.g. `p5 server examples --theme grid --open`.\n\n#### Create a sketch file\n\n- `p5 create` creates a JavaScript sketch file named `sketch.js` in the current\ndirectory.\n\n  This is a **JavaScript-only sketch**. The server can run this sketch, or you\n  can paste it into online editors such as the [P5 web\n  editor](https://editor.p5js.org) and\n  [OpenProcessing.org](https://openprocessing.org).\n\n- `p5 create my-sketch.js` creates a JavaScript sketch file named\n  `my-sketch.js`.\n\n- `p5 create my-sketch.html` creates an HTML file named `my-sketch.html` and a\n  JavaScript file named `my-sketch.js`.\n\n- `p5 create my-sketch` creates a folder named `my-sketch`, and creates\n  `index.html` and `sketch.js` files inside this folder.\n\nThe default generated script contains `setup()` and `draw()` functions. The\n`setup()` functions creates a canvas, and the `draw()` functions draws circles\nthat follow the mouse. `--options` can be used to customize this script.\nSee the reference, below.\n\n### Build a static site\n\n`p5 build SOURCES` builds a static site into `./build`.\n\nRun `p5 build --help` for a list of options.\n\nTwo themes are supported, `--theme grid` and `--theme split`.\n\n### Create a screenshot\n\n`p5 screenshot my-sketch.js` creates a screenshot named `my-sketch.png` in the\ncurrent directory. It operates by running the sketch in a browser, saving the\ncanvas, and then closing the browser page.\n\nYou can also use `p5 screenshot my-sketch.html` for an HTML sketch; and `p5\nscreenshot dir` where `dir` names a single-sketch directory.\n\nRun `p5 screenshot --help` for a list of options. There are options to set the\noutput filename, the number of the starting frame, the pixel density, the canvas\ndimensions, and the browser (Safari, Chrome, Firefox, or Edge).\n\nNotes:\n\n- Only the canvas is saved, not the HTML. Elements created with\n  `createButton()`, `createDiv()` etc. are not captured in the screenshot.\n- The screenshot feature has not been tested with instance-mode sketches.\n\n### Convert between JavaScript-only and HTML sketches\n\n`p5 convert sketch.html` converts an HTML sketch to a JavaScript-only sketch, by\ndeleting the HTML file. It first inspects this file, to insure that the sketch\ncontains only a single script file, and that all the information necessary to\nrun the sketch is in the script.\n\n`p5 convert sketch.js` creates an HTML file that can be used to run the sketch.\n\n## Command-Line Reference\n\nRun `p5 --help` to see a list of commands.\n\nRun `p5 \u003ccommand\u003e --help` to see command-line options for a particular command.\n\n### `p5 build [DIRECTORY]`\n\n- `p5 build` creates an HTML index for a collection of sketches.\n- `p5 build -o out` places the index in the `./out` directory.   (The default is\n  `./build`.)\n\n### `p5 convert FILENAME --to FORMAT`\n\n\u003e Converts between HTML and JavaScript-only sketches.\n\n- `p5 convert FILENAME --to html` creates an HTML file that uses the `\u003cscript\u003e`\n  tag to include the JavaScript sketch.\n- `p5 convert FILENAME --to javascript` removes an HTML file, leaving only the JavaScript file.\n\nConverting a JavaScript-only sketch is simple. An HTML file with the same base\nname is created, that includes the script, the p5.js source (from a CDN), and\nany inferred libraries. This will fail if the directory already contains a\nHTML file with this name.\n\nConverting an HTML sketch to a JavaScript-only sketch involves deleting the HTML file that\nincludes the script. This potentially looses some information. Before the file is deleted,\nthe following checks are made:\n\n- The HTML file includes only a single script file.\n- The libraries that the HTML file includes (via `\u003cscript\u003e` tags) are the same\n  as the libraries that will be inferred from the script file, based on the\n  classes and functions that the script file uses and does not define.\n\n### `p5 create [NAME]`\n\n\u003e Create a JavaScript-only sketch; or an HTML file and a JavaScript file.\n\n- `p5 create` – creates `sketch.js`\n- `p5 create my-sketch.js` – creates just the JavaScript file\n- `p5 create my-sketch.html` – creates `my-sketch.html` and `my-sketch.js`\n- `p5 create my-sketch --type folder` – creates a folder named `my-sketch`, that\n  contains files `index.html` and `sketch.js`.\n\n`p5 create --options comments,preload` specifies a comma-separated set of\ntemplate options. The options are:\n\n- `comments` – include comments (e.g. `// put setup code here`) inside the\n  functions\n- `preload` – include an (empty) `preload()` function\n- `windowResized` – include a `windowResized()` function, that resizes the\n  canvas when the window is resized\n- `no-draw` – omit the `draw()` function, in order to create a \"static\" sketch\n- `no-examples` – omit the example call inside of `draw()`\n\n### `p5 serve [filename]`\n\n\u003e Runs a web server that knows about p5.js sketches.\n\nor the `filename` subdirectory of the current directory.\n\n`p5 serve filename` runs a sketch in the browser.\n\n- If `filename` is an HTML file (for example, `index.html`), this command serves\n  that page.\n- If `filename` is a JavaScript file that contains a p5.js sketch (for example,\n  `sketch.js`), the server serves a page that runs the sketch.\n- If `filename` is a directory, the browser displays a list of sketches and files in that directory.\n- If `filename` is not supplied, the browser displays sketches and files in the\n  current directory. (This is the same as `p5 serve .`.)\n\nBy default, the server runs on port 3000. You can open it in a browser by\nvisiting \u003chttp://localhost:3000\u003e. The `p5 server --open` will do this\nautomatically.\n\nIf another server is already running on port 3000, the server will choose\nanother port.\n\n### `p5 screenshot [filename]`\n\n\u003e Open the sketch in a browser, and save the canvas as an image.\n\n### `p5 tree [DIRECTORY]`\n\n\u003e Display the contents of *DIRECTORY*, organized by sketch.\n\n```text\n$ p5 tree examples\n📁examples\n├── 🎨circles (circles.js)\n├── 🎨sketch\n│   ├── sketch.html\n│   ├── main.js\n│   └── helper.js\n├── 🎨sketch-dir\n│   ├── index.html\n│   └── sketch.js\n├── 🎨squares (squares.js)\n├── 🎨syntax-error\n│   ├── index.html\n│   └── sketch.js\n├── 📁collection\n│   ├── 🎨sketch 1 (sketch-1.js)\n│   ├── 🎨sketch 2 (sketch-2.js)\n│   └── README.md\n├── 📁libraries\n│   ├── 🎨dat.gui (dat.gui.js)\n│   ├── 🎨layers (layers.js)\n│   ├── 🎨posenet (posenet.js)\n│   ├── 🎨sound\n│   │   ├── sound.js\n│   │   └── doorbell.mp3\n│   ├── 🎨sound pulse (sound-pulse.js)\n│   ├── 🎨vector arguments (vector-arguments.js)\n│   └── README.md\n└── README.md\n```\n\nThis is similar to what the Sketch Explorer view in the [Visual Studio Code\nextension](https://github.com/osteele/vscode-p5server#readme) displays.\n\n### Additional commands\n\nAdditional command-line tools are listed [here](https://osteele.github.io/p5-server/p5-analysis/#usage).\n\n## Implementation Notes\n\nThe [p5-analysis implementation\nnotes](./p5-analysis/README.md#implementation-notes) describe sketch detection,\nautomatic library inclusion, and other details of the implementation.\n\n## Limitations\n\n- This code hasn't been tested on Windows.\n- Generated sketches require an internet connection the first time you run the\n  server on a machine. Sketches load the p5.js and other libraries from a\n  content delivery network (“CDN”). These libraries are cached (in\n  `~/.cache/p5-server`), so that reloading a page or running other sketches that\n  use the same (or no) libraries does not require additional internet access.\n- This code hasn't been tested with\n  [instance-mode](https://github.com/processing/p5.js/wiki/Global-and-instance-mode)\n  sketches.\n- Automatic library inclusion hasn't been tested with sketches that are written\n  as\n  [modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).\n- This is a development server, not a production server. It was not designed for\n  security or performance.\n- See the [p5-analysis implementation\n  notes](./p5-analysis/README.md#implementation-notes) notes for limitations on\n  the recognition of associated files.\n\n## API\n\nThe server can be invoked programmatically. See the [API Reference](https://osteele.github.io/p5-server/p5-analysis/) for installation instructions and reference documentation for this use.\n\n## Acknowledgements\n\nThis project builds on these libraries and frameworks:\n\n- commander, chalk, and update-notifier for command-line-y stuff\n- esprima and node-html-parser for parsing JavaScript and HTML, respectively\n- expressjs for the web server\n- livereload for the live reload functionality\n- marked for converting Markdown to HTML\n- nunjucks and pug for template generation\n- The Semantic UI CSS framework\n- And of course [p5.js](https://p5js.org/)\n\n## Other Work\n\n[https://code.osteele.com](https://code.osteele.com#p5-js) lists my other p5.js\nprojects. These include tools, libraries, and examples and educational\nmaterials.\n\n## Keeping in Touch\n\nReport bugs, features requests, and suggestions\n[here](https://github.com/osteele/p5-server/issues).\n\n## License\n\n[MIT](LICENSE) © by Oliver Steele\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fp5-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosteele%2Fp5-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fp5-server/lists"}