Repository navigation
Architecture
p5.nvim is split across three runtimes that talk to each other over localhost sockets:
flowchart LR
NV["Neovim\nlua/p5/*.lua"] -->|"http/curl"| SRV["server.py\nasyncio HTTP + WS"]
NV -->|"jobstart +\n--remote-debugging-port"| CR["Chrome (isolated)"]
SRV -->|"http /json\nCDP WebSocket"| CR
CR -->|"Performance.metrics\nRuntime.evaluate"| SRV
SRV -->|"SSE /api/console/stream"| NV
NV -->|"render 6-tab panel"| UI["HUD window"]
CR -.->|"EventSource /api/console/stream\nWebSocket ws://localhost:12002"| SRV
lua/p5/
βββ init.lua # setup(), config defaults, autocmds
βββ commands.lua # :P5 subcommand dispatch + interactive picker
βββ core.lua # path resolution, caching, utils, Chrome discovery
βββ project.lua # sketchspace scaffolding (p5.json, templates)
βββ server.lua # server lifecycle, port allocation, health checks
βββ libraries.lua # p5.js + contrib library management
βββ gist.lua # Gist create/sync/edit, sketchbook cloning
βββ cdp.lua # CDP panel: HUD, tabs, eval, breakpoints, perf
βββ health.lua # :checkhealth p5
sequenceDiagram
participant N as Neovim
participant S as server.py
participant P as Python process
N->>S: :P5 server (start)
S->>P: jobstart python3 server.py --port 8000
P-->>S: stdout lines (URL, port)
S->>S: polls /api/health until ready
S->>N: notify "Server running on http://localhost:8000"
The Lua side spawns server.py as a job, parses its stdout for the actual bound port (requested port may be taken), and keeps the job reference in server.server_job.
:P5 create/:P5 setup writes runtime assets (p5.js, libs.js, p5.d.ts) into assets/libs inside the sketchspace, hydrating from the version cache at ~/.cache/p5.nvim/versions or falling back to a CDN. index.html is generated from a template and injects the runtime + console/livereload scripts.
-
console.jsis injected into the page and hooksconsole.log/warn/error/info. - Messages are POSTed to
/api/console/log(or forwarded via the CDP debugger events when the panel is connected). - Neovim consumes a Server-Sent Events stream at
/api/console/streamand appends entries to the Console tab. - While CDP is connected, the injectable hook is bypassed via the
__P5_CDP_ACTIVEflag so messages are captured exactly once.
init.lua setup(opts) deep-merges user options into module-level config tables:
flowchart LR
USR["user opts"] --> SETUP["setup()"]
SETUP --> CORE["core.config"]
SETUP --> PRJ["project.config"]
SETUP --> SRV["server.config"]
SETUP --> LIB["libraries.config"]
SETUP --> GIST["gist.config"]
SETUP --> CDP["cdp.config"]
The dev server reads the same settings from p5.json and the config passed via CLI flags (--port, --live-reload-port, --cdp-port, β¦).
-
No server dependencies β
server.pyuses onlyasyncio,json, andhttp.serverfrom the standard library, pluswebsocketsfor live reload (a soft import β live reload degrades gracefully if it is missing). -
Isolated Chrome β the CDP panel launches Chrome with a throwaway
--user-data-dirand binds debugging to127.0.0.1, so a normal browser session is never disturbed and the port is always available. -
Non-blocking β long-running loops (file watcher, SSE stream, CDP event stream) all run in the server's
asyncioevent loop; Neovim stays responsive.