https://github.com/prjctimg/p5.nvim
Better editor support for p5.js 🌸 sketchspaces in Neovim
https://github.com/prjctimg/p5.nvim
live-server lua manpages neovim p5-js snippets typescript
Last synced: 3 days ago
JSON representation
Better editor support for p5.js 🌸 sketchspaces in Neovim
- Host: GitHub
- URL: https://github.com/prjctimg/p5.nvim
- Owner: prjctimg
- License: gpl-3.0
- Created: 2026-01-07T15:55:10.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-09T04:21:16.000Z (6 days ago)
- Last Synced: 2026-04-09T06:21:02.803Z (6 days ago)
- Topics: live-server, lua, manpages, neovim, p5-js, snippets, typescript
- Language: JavaScript
- Homepage:
- Size: 4.74 MB
- Stars: 17
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# `p5.nvim` 🌸
> Better editor support for p5.js sketchspaces in Neovim.
[](https://github.com/prjctimg/p5.nvim/releases/latest)
---
## On this page
- [Features ✨](#features)
- [Requirements 📋](#requirements-📋)
- [Installation 💾](#installation-💾)
- [What's a sketchspace ?](#whats-a-sketchspace)
- [Quick Start 🚀](#quick-start-🚀)
- [Commands 📖](#commands-📖)
- [Configuration ⚡](#configuration)
- [Auto Commands 🔌](#auto-commands-🔌)
- [Keyboard Shortcuts ⌨️](#keyboard-shortcuts-️)
- [Troubleshooting 🔧](#troubleshooting-🔧)
- [License 📜](#license-📜)
---
## Features ✨
- **Live Server** 🚀 - Auto-reload preview in browser
- **Package Management** 📦 - Install contributor libraries
- **Sketchspace** 📁 - Minimal project setup
- **GitHub Gist** 🔗 - Share sketches (synced to sketchspace)
- **Console** 📺 - View browser logs in Neovim
- **p5.js Docs** 📖 - Built-in reference via snacks.picker
---
## Requirements 📋
- `nvim` >= 0.11.0
- Python 3.7+ (for development server)
- [websockets](https://pypi.org/project/websockets/) Python package (`python3-websockets` on Debian/Ubuntu, or `sudo pipx install websockets`)
- `curl` (for console streaming)
- `lsof` (checking ports)
---
## Installation 💾
```lua
-- lazy.nvim (installs latest release)
{
"prjctimg/p5.nvim",
dependencies = {
"nvim-lua/plenary.nvim",
},
config = function()
require("p5").setup({})
end
}
```
---
## What's a sketchspace ?
A directory that has a `p5.json` file is called a `sketchspace`. The file looks like this:
```json
{
"version": "1.9.0",
"libs": {
"ml5": "latest"
},
"includes": ["sketch.js"],
"gist": "https://gist.github.com/..."
}
```
- `version`: p5.js version to use
- `libs`: Object with library names as keys and their versions as values
- `includes`: Files to include in the Gist (default: `["sketch.js"]`)
- `gist`: URL of associated GitHub Gist (optional)
> [!important]
>
> This file is needed for setting up and running `sketchspaces`.
>
> It currently only works with this plugin.
---
## Quick Start 🚀
```vim
:P5 create my-sketch
:P5 server
:P5 console
```
---
## Commands 📖
### :P5 create [name]
Create a new sketchspace.
```vim
:P5 create my-sketch
:P5 create
```
[](https://asciinema.org/a/795753)
---
### :P5 setup
Setup assets in current sketchspace.
Downloads files from gist (if configured), creates default sketch.js if missing, copies assets, generates libs.js, and installs configured libraries.
```vim
:P5 setup
```
---
### :P5 install [libs...]
Install contributor libraries. Use picker or specify directly.
```vim
:P5 install ml5
:P5 install ml5 rita p5play
:P5 install
```
### :P5 uninstall [libs...]
Remove installed libraries.
```vim
:P5 uninstall ml5
:P5 uninstall
```
[](https://asciinema.org/a/795789)
---
### :P5 server [port]
Start/stop the development server (toggle). Opens browser automatically and enables live reload.
```vim
:P5 server
:P5 server 8080
```
---
### :P5 console
Toggle browser console to view console.log, errors, and warnings in Neovim.
```vim
:P5 console
```
[](https://asciinema.org/a/801611)
---
### :P5 sync [gist|libs]
Sync gist or libraries.
```vim
:P5 sync gist
:P5 sync libs
:P5 sync
```
[](https://asciinema.org/a/801610)
---
### :P5 gist [desc]
Create a GitHub Gist from your sketchspace.
```vim
:P5 gist "My awesome sketch"
:P5 gist
```
[](https://asciinema.org/a/799472)
---
### :P5 docs
Open p5.js documentation via snacks.picker.
```vim
:P5 docs
```
---
## Configuration ⚡
```lua
require("p5").setup({
-- Server settings
server = {
port = 8000, -- Server port
auto_start = false, -- Auto start server when opening sketch.js
auto_open_browser = true, -- Open browser automatically
ready_timeout = 5000, -- Server ready timeout (ms)
fallback_ports = {8001, 8002, 8003}, -- Ports to try if default is busy
-- Live reload settings
live_reload = {
enabled = true, -- Enable live reload
port = 12002, -- Live reload port
debounce_ms = 300, -- Debounce delay
watch_extensions = {".js", ".css", ".html", ".json"}, -- Files to watch
exclude_dirs = {".git", "node_modules", "dist", "build"} -- Exclude directories
}
},
-- Console settings
console = {
position = "below", -- Window position: below, above, left, right
height = 10, -- Window height (lines)
},
-- Library settings
libraries = {
auto_update = false -- Auto update libraries on setup
}
})
```
---
## Auto Commands 🔌
Auto-start server when opening a sketch.js file:
```lua
-- Auto-start server when opening sketch.js
vim.api.nvim_create_autocmd({ "BufEnter" }, {
pattern = "sketch.js",
callback = function()
vim.cmd("P5 server")
end
})
-- Auto-open console when server starts
vim.api.nvim_create_autocmd({ "User", "P5ServerStarted" }, {
callback = function()
vim.cmd("P5 console")
end
})
```
---
## Keyboard Shortcuts ⌨️
Example keybindings using `p` prefix:
```lua
-- General
vim.keymap.set("n", "p5", ":P5", { desc = "Open p5.nvim picker" })
-- Project
vim.keymap.set("n", "pc", ":P5 create ", { desc = "Create project" })
vim.keymap.set("n", "ps", ":P5 setup", { desc = "Setup project" })
-- Server
vim.keymap.set("n", "pss", ":P5 server", { desc = "Toggle server" })
vim.keymap.set("n", "pso", ":P5 console", { desc = "Toggle console" })
-- Libraries
vim.keymap.set("n", "pi", ":P5 install ", { desc = "Install library" })
vim.keymap.set("n", "pu", ":P5 uninstall ", { desc = "Uninstall library" })
vim.keymap.set("n", "pU", ":P5 sync libs", { desc = "Update libraries" })
-- Gist
vim.keymap.set("n", "pg", ":P5 gist ", { desc = "Create gist" })
vim.keymap.set("n", "pgg", ":P5 sync gist", { desc = "Sync gist" })
-- Docs
vim.keymap.set("n", "pd", ":P5 docs", { desc = "Open p5.js docs" })
```
---
## Troubleshooting 🔧
### Server Won't Start
**Symptoms:** Running `:P5 server` shows an error or nothing happens.
**Solutions:**
1. Ensure Python 3 is installed:
```bash
python3 --version
```
2. Check if the port is already in use:
```bash
lsof -i :8000
```
3. Try a different port:
```vim
:P5 server 8080
```
1. Check Neovim notifications for specific error messages
### Downloads Not Working
Library installation fails or downloads timeout.
**Solutions:**
1. Ensure curl is installed:
```bash
curl --version
```
2. Check internet connection:
```bash
curl -I https://cdnjs.cloudflare.com
```
3. Verify firewall isn't blocking `localhost` connections
4. Check that you're in a valid sketchspace (has `p5.json`)
### Gist Upload/Sync Fails
`:P5 gist` or `:P5 sync gist` shows an error.
**Solutions:**
1. Ensure GitHub CLI is installed:
```bash
gh --version
```
2. Authenticate with GitHub:
```bash
gh auth login
```
3. Verify gist URL in `p5.json` is valid:
```vim
:edit p5.json
```
4. For sync failures, the gist may have been deleted - run `:P5 gist` to create a new one
### Library Install/Uninstall Fails
`:P5 install` or `:P5 uninstall` shows an error.
**Solutions:**
1. Verify you're in a sketchspace (directory with a `p5.json` file):
```bash
ls p5.json
```
2. Check assets/libs directory is writable:
```bash
ls -la assets/libs
```
3. Run setup first to initialize:
```vim
:P5 setup
```
---
> ## License 📜
> (c) 2026, [Dean Tarisai](https://prjctimg.me)
>
> This is free software, released under the GPL-3.0 license.
---
---