Plugin Manifest
Complete reference for the plugin.json manifest file schema.
Overview#
Every NaaP plugin must include a plugin.json file at its root. This manifest defines the plugin's identity, routes, backend configuration, database schema, and more.
Complete Schema#
JSON
| 1 | { |
| 2 | "name": "my-plugin", |
| 3 | "displayName": "My Plugin", |
| 4 | "version": "1.0.0", |
| 5 | "description": "What the plugin does", |
| 6 | "category": "monitoring", |
| 7 | "author": "Your Name", |
| 8 | "license": "MIT", |
| 9 | "repository": "https://github.com/user/plugin", |
| 10 | |
| 11 | "frontend": { |
| 12 | "entry": "./frontend/dist/production/my-plugin.js", |
| 13 | "devPort": 3010, |
| 14 | "routes": ["/my-plugin", "/my-plugin/*"], |
| 15 | "navigation": { |
| 16 | "label": "My Plugin", |
| 17 | "icon": "Activity", |
| 18 | "section": "main", |
| 19 | "order": 50 |
| 20 | } |
| 21 | }, |
| 22 | |
| 23 | "backend": { |
| 24 | "entry": "./backend/dist/server.js", |
| 25 | "port": 4010, |
| 26 | "apiPrefix": "/api/v1/my-plugin", |
| 27 | "healthCheck": "/healthz" |
| 28 | }, |
| 29 | |
| 30 | "database": { |
| 31 | "type": "postgresql", |
| 32 | "schema": "plugin_my_plugin" |
| 33 | }, |
| 34 | |
| 35 | "permissions": { |
| 36 | "required": ["read:data"], |
| 37 | "optional": ["write:data", "admin:settings"] |
| 38 | }, |
| 39 | |
| 40 | "config": { |
| 41 | "schema": { |
| 42 | "pageSize": { "type": "number", "default": 20 }, |
| 43 | "enableNotifications": { "type": "boolean", "default": true } |
| 44 | } |
| 45 | } |
| 46 | } |
Field Reference#
Root Fields#
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique plugin identifier (kebab-case) |
displayName | string | Yes | Human-readable name shown in UI |
version | string | Yes | Semantic version (e.g., 1.0.0) |
description | string | No | Brief description |
category | PluginCategory | Yes | Plugin category |
author | string | No | Plugin author name |
license | string | No | License identifier |
repository | string | No | Source code URL |
Frontend Configuration#
| Field | Type | Required | Description |
|---|---|---|---|
frontend.entry | string | Yes | Path to UMD bundle entry |
frontend.devPort | number | No | Development server port |
frontend.routes | string[] | Yes | URL routes handled by this plugin |
frontend.navigation.label | string | Yes | Sidebar label |
frontend.navigation.icon | string | No | Lucide icon name |
frontend.navigation.section | string | No | Sidebar section (main or network) |
frontend.navigation.order | number | No | Sort order in sidebar |
Backend Configuration#
| Field | Type | Required | Description |
|---|---|---|---|
backend.entry | string | Yes | Path to compiled server |
backend.port | number | Yes | Server port |
backend.apiPrefix | string | Yes | API route prefix |
backend.healthCheck | string | No | Health check endpoint path |
Database Configuration#
| Field | Type | Required | Description |
|---|---|---|---|
database.type | string | Yes | Database type (currently only postgresql) |
database.schema | string | Yes | PostgreSQL schema name (e.g., plugin_my_plugin) |
Architecture: NaaP uses a single database with multi-schema isolation. The
schemafield identifies which PostgreSQL schema this plugin owns. All Prisma models are defined centrally inpackages/database/prisma/schema.prisma. See Database Architecture.
Permissions#
| Field | Type | Description |
|---|---|---|
permissions.required | string[] | Permissions the plugin needs to function |
permissions.optional | string[] | Permissions that enhance functionality |
Configuration Schema#
Define user-configurable settings:
JSON
| 1 | { |
| 2 | "config": { |
| 3 | "schema": { |
| 4 | "pageSize": { |
| 5 | "type": "number", |
| 6 | "default": 20, |
| 7 | "description": "Number of items per page" |
| 8 | }, |
| 9 | "theme": { |
| 10 | "type": "string", |
| 11 | "default": "auto", |
| 12 | "enum": ["auto", "compact", "expanded"], |
| 13 | "description": "Display theme" |
| 14 | } |
| 15 | } |
| 16 | } |
| 17 | } |
Navigation Icons#
The navigation.icon field accepts any Lucide icon name:
| Icon Name | Use Case |
|---|---|
Activity | Monitoring, health |
BarChart3 | Analytics, dashboards |
Code | Developer tools |
Cpu | Infrastructure |
Radio | Networking |
Shield | Security |
Video | Media, streaming |
Wallet | Finance |
Users | Community, teams |
Zap | Performance |
Validation#
Run the doctor command to validate your manifest:
Terminal
$naap-plugin doctor
This checks for:
- Required fields are present
- Version follows semver
- Routes are valid URL patterns
- Ports are in valid ranges
- Referenced files exist