Skip to content

RosPanel plugins

Русская версия

A plugin is JavaScript that runs inside the panel. It reacts to events, runs on a schedule, keeps its own data and calls the panel's API and the internet — only as far as the operator agreed when installing it. Plugins are in beta.

What a plugin can do

Task How Example
React to events: sign-ups, payments, ending subscriptions, a server going down onEvent new-users, notify-discord
Do something on a schedule cron users-csv
Add a payment method payment lava
Take requests from the internet: a shop, a form, OAuth onHttp shop-webhook
Show data on a user's card, buttons, dashboard widgets userFields, onAction, widget email
Blocks and a theme on the subscription page subBlocks, theme announcement, theme-night
Deliver messages to those the bot does not reach (e-mail, SMS) channel email
Decide who may sign up, which device may bind, what price to give beforeSignup, beforeDeviceBind, quotePrice channel-gate
Buttons and commands in the user bot bot channel-gate
Change the configs clients are served transformSubscription —

Quick start

Everything is built into rospanel; no Node.js needed.

rospanel plugin new my-plugin   # a working plugin from the template
cd my-plugin
rospanel plugin test .          # tests
rospanel plugin dev .           # a console that reloads on save
rospanel plugin pack .          # my-plugin-0.1.0.zip

Install the zip in the panel: Settings → Plugins → Add. Or write the plugin in the panel itself — see the editor.

// main.js — the panel calls what is exported
export function onEvent(e) {
  if (e.event === "user.created") panel.log.info("new user", e.data.name);
}

Documentation

  1. The plugin editor in the panel — the rule builder, the code editor, tests and a trial run, without leaving the panel.
  2. Your first plugin, step by step — from plugin new to installing it, with Telegram notifications as the example.
  3. Manifest and package — all of plugin.json: permissions, hosts, settings, points, resources.
  4. Extension points — every export: when it is called, what it gets, what to return, time limits.
  5. Plugin API — panel.config, log, kv, db, api, http.fetch, blob, crypto, t.
  6. Testing and debugging — test.js, mocks, dev, validate, the log in the panel.
  7. Publishing and updates — versions, migrations, rollback, sharing a plugin.
  8. Limits, security and errors — the sandbox, limits, pausing, common errors explained, questions.

Editor types are in rospanel.d.ts, which plugin new puts in the folder. Events and their fields are in docs/api.md, the API's routes in your panel's /v1/docs.

The essentials

  • Synchronous code. Every panel.* call is synchronous. There are no timers.
  • At-least-once delivery. An event may come twice; handle it idempotently.
  • State in storage. Keep it in panel.kv/panel.db, not in variables: the VM may be restarted between calls.
  • Errors and retries. A thrown exception is an error: the event is delivered again, and after 10 errors in a row the plugin is paused until the panel retries it.
  • Least privilege. Ask only for the permissions and hosts you need: the operator sees them before installing.