Velocity

Developers

Create a plugin

Plugins are small HTML apps that run as tiles inside Velocity. Ship a manifest, an entry page, and talk to the host through window.VelocityPlugin.

Full markdown guide on GitHub: DEVELOPERS.md

What a plugin is

A plugin is a folder with:

Examples in the repo: spotify, aura-wallpapers.

Quick start

Manifest:

{
  "id": "com.example.hello",
  "name": "Hello",
  "version": "0.1.0",
  "description": "Minimal Velocity plugin",
  "icon": "assets/icon.svg",
  "entry": "ui/index.html",
  "permissions": []
}

Use a stable reverse-DNS id. UI skeleton:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Hello</title>
  </head>
  <body>
    <h1>Hello</h1>
    <button type="button" id="done">Close</button>
    <script src="./app.js"></script>
  </body>
</html>
const api = window.VelocityPlugin;
api.ready();
api.onHostMessage((msg) => {
  if (msg.type === "velocity:theme" || msg.type === "velocity:ready") {
    // apply msg.theme.mode / msg.theme.accent
  }
});
document.getElementById("done").onclick = () => api.close();

Relative <script src="./…"> files are inlined by the host. Keep app code local to the plugin folder.

Install while developing

  1. Open Velocity → Plugins.
  2. Copy your folder into the user plugins directory.
  3. Tap Refresh, then open the tile from home.

Typical path on macOS:

~/Library/Application Support/com.inertiaux.velocity/plugins/

Host bridge

window.VelocityPlugin is injected automatically.

Method Purpose
ready() Signal that the UI mounted
close() Return to the home screen
toast(message) Ask the host for a toast (reserved)
request(method, params?) Promise-based host call
onHostMessage(handler) Theme / responses; returns unsubscribe

Common request methods: wallpaper:get, wallpaper:apply, wallpaper:clear.

Permissions you may declare: network, media, wallpaper, plus reserved filesystem, notifications, clipboard.

Wallpaper plugins

Set provides: ["wallpaper"], permission wallpaper, and a wallpapers array:

{
  "permissions": ["wallpaper"],
  "provides": ["wallpaper"],
  "wallpapers": [
    {
      "id": "harbor",
      "name": "Harbor",
      "css": "linear-gradient(180deg, #0b1f2a, #7fd3c2)"
    }
  ]
}
await VelocityPlugin.request("wallpaper:apply", {
  pluginId: "com.example.pack",
  id: "harbor",
  css: "linear-gradient(180deg, #0b1f2a, #7fd3c2)",
});

Security

Full guide on GitHub Source