Skip to content

LiveReload

prjctimg edited this page Aug 5, 2026 · 1 revision

Live Reload

The dev server keeps the browser in sync with your sketch automatically, through two complementary mechanisms.

File Watcher + WebSocket

The server watches the sketchspace and broadcasts reloads over a WebSocket to the injected livereload.js:

sequenceDiagram
    participant E as Editor (save)
    participant W as File watcher
    participant S as server.py
    participant P as Browser (livereload.js)
    E->>W: BufWritePost (or FS event)
    W->>S: change detected (debounced 300ms)
    S-->>P: ws://localhost:12002 reload message
    P-->>P: location.reload()
Loading
  • Debounce — server.live_reload.debounce_ms (300ms) coalesces bursts of saves
  • Watched extensions — .js, .css, .html, .json (configurable)
  • Excluded dirs — .git, node_modules, dist, build (configurable)

CDP Reload (debug mode)

When the CDP panel is connected, reloads can be issued through Chrome instead:

:P5 cdp reload

This sends Page.reload with ignoreCache: true, so the browser fetches a fresh copy of sketch.js and libraries even if they are HTTP-cached. This is the most reliable way to see asset changes while debugging.

Which One Runs?

Both mechanisms can be active; the rule is simple:

  1. No CDP panel → injected livereload.js + WebSocket reload on watched-file changes.
  2. CDP panel connected → use :P5 cdp reload for a cache-bypassing reload; the file watcher still broadcasts over the WebSocket for any page loaded from the server.

The refresh_on_save autocmd (autocmds.refresh_on_save = true) triggers a reload immediately on BufWritePost, without waiting for the file-watcher debounce.

Why the Cache Matters

p5.nvim serves p5.js and libraries with long-lived cache headers keyed by version. While that is great for startup speed, it means an edited library file can appear stale. Page.reload with ignoreCache sidesteps the cache entirely — which is exactly what you want during a debugging session.

Clone this wiki locally