p5-webeditor-sync

CLI and npm package for batch publishing local p5.js project folders to editor.p5js.org.

Extracted from the sync workflow in preposition-programming. Consumer repos keep sketch generation and export scripts; this package handles auth, payload building, create/update, registry, and verification.

Install

npm install -D p5-webeditor-sync

Requires Node 20+.

For browser login, also install Playwright in your project:

npm install -D playwright
npx playwright install chromium

Quick Start

Use p5-webeditor-sync when you already have one or more local p5.js sketches and want to publish them to the p5 Web Editor from the command line.

The CLI expects each sketch to be a folder. A single-sketch project might look like this:

my-p5-work/
  webeditor/
    projects/
      bouncing-ball/
        index.html
        sketch.js
        meta.json

A batch project can contain many sketch folders:

my-p5-work/
  webeditor/
    projects/
      bouncing-ball/
        index.html
        sketch.js
        meta.json
      particle-field/
        index.html
        sketch.js
        meta.json
      clock/
        index.html
        sketch.js
        meta.json

1. Install

From the root of the project that contains your sketches:

npm install -D p5-webeditor-sync

If you want to use the browser-based login command, install Playwright too:

npm install -D playwright
npx playwright install chromium

You can also skip Playwright and use cookie import or the P5_EDITOR_COOKIE environment variable. See Auth.

2. Create Sketch Folders

Each sketch folder should contain the files the Web Editor should receive. At minimum, this is usually index.html and sketch.js:

webeditor/projects/bouncing-ball/
  index.html
  sketch.js
  meta.json

Example meta.json:

{
  "slug": "bouncing-ball",
  "title": "Bouncing Ball"
}

For an existing Web Editor project, add its sketch ID so the CLI updates it instead of creating a new project:

{
  "slug": "bouncing-ball",
  "title": "Bouncing Ball",
  "editorSketchId": "abc123xyz"
}

The sketch ID is the final part of a Web Editor URL:

https://editor.p5js.org/your-username/sketches/abc123xyz

3. Add Config

Create p5-webeditor.config.json at your project root:

{
  "$schema": "https://unpkg.com/p5-webeditor-sync/schema/config.json",
  "account": "your-username",
  "projectsDir": "webeditor/projects",
  "syncDir": "webeditor/.sync",
  "registryFile": "webeditor/.sync/registry.json",
  "namePrefix": "",
  "visibility": "Public",
  "batches": {
    "all": ["my-sketch"]
  },
  "verify": {
    "enabled": true,
    "signature": "unique string in sketch.js",
    "mode": "local",
    "skipIfMissing": true,
    "failOnVerify": false
  }
}

For one sketch, batches.all can contain one slug:

{
  "batches": {
    "all": ["bouncing-ball"]
  }
}

For many sketches, list all slugs or split them into named batches:

{
  "batches": {
    "experiments": ["bouncing-ball", "particle-field"],
    "finished": ["clock"],
    "all": ["bouncing-ball", "particle-field", "clock"]
  }
}

If all is omitted or empty, the CLI computes it from the other batches and auto-discovers sketch folders under projectsDir.

4. Log In Once

Option A — browser (Playwright):

npx p5-webeditor-sync login

Option B — DevTools cookie (no Playwright):

p5-webeditor-sync cookie import --cookie 'connect.sid=...; ...'

This opens a browser (Option A), or validates and saves a cookie (Option B). Session file: ~/.config/p5-webeditor-sync/session.json.

Check that the session works:

npx p5-webeditor-sync session

5. Dry Run

Before uploading anything, check what would happen:

npx p5-webeditor-sync sync --batch all --dry-run

Or with push only:

npx p5-webeditor-sync push --batch all --dry-run

For one sketch:

npx p5-webeditor-sync push --slug bouncing-ball --dry-run

The CLI prints whether each sketch would be created or updated.

6. Prepare Payloads (Optional)

push builds payloads automatically, but prepare is useful when you want to inspect the Web Editor file payload first:

npx p5-webeditor-sync prepare --batch all

Payload JSON is written under your configured syncDir, usually webeditor/.sync/.

7. Push To The Web Editor

Recommended: prepare + push in one step:

npx p5-webeditor-sync sync --batch all

Create or update all sketches (push only):

npx p5-webeditor-sync push --batch all

Push a single sketch:

npx p5-webeditor-sync push --slug bouncing-ball

Push a named batch:

npx p5-webeditor-sync push --batch experiments

The first successful create stores the returned Web Editor project ID in registryFile. Later runs reuse stable file IDs and update the same project.

8. Verify Live Sketches

Verification defaults to local file mode: it checks exported project files for verify.signature (e.g. a CDN pin in index.html). Sketches that do not contain the signature are skipped, not failed.

npx p5-webeditor-sync verify --batch all

Configure in p5-webeditor.config.json:

"verify": {
  "enabled": true,
  "signature": "[email protected]",
  "mode": "local",
  "skipIfMissing": true,
  "failOnVerify": false
}

Per-sketch overrides in meta.json: "verify": false, "verifySignature": "...", or "verifySkipIfMissing": false.

9. Repeat Syncs

On later runs, unchanged sketches are skipped by content hash:

npx p5-webeditor-sync sync --batch all

If a batch fails midway, resume after fixing the issue:

npx p5-webeditor-sync sync --batch all --resume

Force upload even when the hash has not changed:

npx p5-webeditor-sync sync --batch all --force

Project Folders

Each publishable sketch is a directory under projectsDir:

webeditor/projects/above/
  index.html
  sketch.js
  helpers.js
  meta.json

meta.json supplies slug, title, and optional editorSketchId for updates. Optional verify overrides: verify, verifySignature, verifyMode, verifySkipIfMissing. See docs/VERIFY.md. meta.json is not uploaded to the Web Editor.

Nested files are supported one folder deep, for example:

webeditor/projects/above/
  index.html
  sketch.js
  shared/
    palette.js

sketch.js is marked as the selected file in the Web Editor payload.

Config Reference

Common config fields:

| Field | Description | |-------|-------------| | account | Your p5 Web Editor username | | projectsDir | Folder containing one sketch folder per slug | | syncDir | Local output folder for payloads, results, and registry | | registryFile | Stable mapping of slug to Web Editor project ID, file IDs, and content hash | | namePrefix | Optional prefix added to Web Editor project names | | visibility | Public or Private | | batches | Named sets of slugs for batch upload | | verify.signature | Text expected in project files (default mode) or full-preview HTML (mode: "preview") | | verify.mode | local (default), preview, or auto | | verify.skipIfMissing | Skip verify when signature is absent from project files (default true) | | verify.failOnVerify | When false (default), verify problems warn but do not fail push/sync |

Commands

See docs/COMMANDS.md for full flag reference.

| Command | Description | |---------|-------------| | login | Open browser, save session to ~/.config/p5-webeditor-sync/session.json | | session | Validate session and print logged-in username | | cookie import | Save P5_EDITOR_COOKIE or --cookie to session file | | prepare | Build payload JSON under syncDir | | push | POST new projects or PUT updates; supports --resume, --force, --dry-run | | sync | prepare + push (recommended batch command) | | verify | Check projects against verify.signature | | links apply | Sync editorSketchId from webeditorLinks.md into a manifest JSON |

Auth

See docs/AUTH.md for login, cookie import, saved sessions, and P5_EDITOR_COOKIE.

Programmatic API

See docs/API.md for imports and examples.

import { loadConfig, syncBatch, validateSession, verifyProject } from "p5-webeditor-sync";

Development

npm test
npm link
p5-webeditor-sync --version

Publishing

This repo publishes directly to npmjs.com with the npm CLI, following the same local release pattern as p5-phone.

Authenticate once with a granular npm token:

npm config set //registry.npmjs.org/:_authToken YOUR_TOKEN
npm whoami

Then publish the current version:

npm test
npm publish

For later releases, bump, tag, and push with npm:

npm run release:patch
npm publish

Use release:minor or release:major when appropriate. prepublishOnly runs tests before every publish.

Documentation

• Commands reference
• Authentication
• Verification
• Programmatic API
• Planning document

License

MIT