NexaDash/docs/plugins

NexaDash Plugin Developer Documentation

Table of Contents

1. What is a NexaDash Plugin?
2. Plugin Structure
3. Manifest
4. Settings & Credentials Schema
5. Widget Schema
6. Backend Connector
7. Frontend Widget
8. Permissions
9. Secrets Handling
10. Background Jobs
11. Error Handling
12. Versioning
13. Testing
14. Security Rules
15. Example: Creating a Plugin
16. Packaging
17. Upload
18. Best Practices

What is a NexaDash Plugin?

A NexaDash plugin is a declarative package that connects an external service to the dashboard. It defines:

• A plugin.manifest.json describing metadata, schemas and widgets.
• A backend connector (declarative or built-in Python class) that fetches data from the service.
• Optional frontend widget components that render the data.

Plugins never execute arbitrary code in the main API process. Connectors are loaded from a known registry and run in a sandboxed layer.

Plugin Structure

my-plugin/
  plugin.manifest.json
  README.md
  widgets/
    MyWidget.tsx
  connector/
    connector.py   (optional, for custom Python connectors)

Manifest

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "nexadashPluginApi": "1.0",
  "description": "Short description",
  "author": "Your Name",
  "category": "Infrastructure",
  "permissions": ["network:outbound", "secrets:read"],
  "settingsSchema": {},
  "credentialsSchema": {},
  "widgets": [],
  "apiRoutes": [],
  "hasFrontend": true,
  "healthcheck": {
    "method": "GET",
    "intervalSeconds": 60,
    "timeoutSeconds": 30
  }
}

Settings & Credentials Schema

Schemas follow JSON Schema with a few conventions:

• format: "password" hides the value in the UI.
• enum renders as a select dropdown.
• Credentials are stored encrypted and never returned to the frontend.

Widget Schema

Each widget needs:

• id: unique widget type identifier.
• name: human-readable label.
• description: short help text.
• defaultWidth, defaultHeight: default grid size.
• settingsSchema: per-widget settings.

Backend Connector

Built-in connectors cover many services. For custom services, you can provide a Python class that extends PluginConnector:

from apps.api.src.plugins.base import PluginConnector

class MyConnector(PluginConnector):
    id = "my-plugin"
    name = "My Plugin"

    async def healthcheck(self):
        return {"status": "ok"}

    async def fetch_widget_data(self, widget_type, settings):
        return {"value": 42}

Register it in apps/api/src/plugins/registry.py.

Frontend Widget

Frontend widgets are React components that receive data and settings props. They are rendered by the dashboard editor.

Permissions

Common permissions:

• network:outbound — plugin may make HTTP requests.
• secrets:read — plugin may decrypt its own credentials.
• jobs:schedule — plugin may schedule background jobs.

Secrets Handling

Never log or return secrets. The backend decrypts credentials only when executing a connector and passes them to the connector instance.

Background Jobs

Use the Celery worker for long-running sync tasks. Schedule via the background_jobs API or from a connector.

Error Handling

Return {status: "error", message: "..."} on failures. The dashboard shows a user-friendly error card.

Versioning

Use semantic versioning. The plugin registry tracks versions in plugin_versions.

Testing

• Validate the manifest with @nexadash/plugin-sdk.
• Test connectors with mocked HTTP clients.
• Add API tests for custom endpoints.

Security Rules

• Only http/https URLs are allowed (SSRF protection).
• No credentials in frontend code.
• No dynamic code execution (eval, exec).
• Use least-privilege API tokens.
• Validate all inputs with schemas.

Example: Creating a Plugin

See plugins/example-plugin/ for a complete working example.

Packaging

Zip the plugin directory with the manifest at the root:

zip -r my-plugin.zip my-plugin/

Upload

Upload the ZIP in the UI under Plugins → Upload Plugin or via the API:

curl -F "file=@my-plugin.zip" https://nexadash.local/api/v1/plugins/upload

Best Practices

• Keep widgets focused on one metric.
• Use pagination for large lists.
• Cache expensive requests in the connector.
• Provide clear error messages.
• Document required credentials.