Plugin Settings Schema

Define configurable settings for your plugins with validation and admin UI integration.

Basic Schema

manifest.json

{
  "settings": {
    "schema": {
      "apiKey": {
        "type": "string",
        "label": "API Key",
        "required": true,
        "secret": true
      },
      "enabled": {
        "type": "boolean",
        "label": "Enable Plugin",
        "default": true
      }
    }
  }
}

Field Types

String

{
  "apiUrl": {
    "type": "string",
    "label": "API URL",
    "description": "The base URL for API requests",
    "default": "https://api.example.com",
    "required": true,
    "validation": "url",
    "placeholder": "https://..."
  }
}

Number

{
  "maxRetries": {
    "type": "number",
    "label": "Max Retries",
    "description": "Maximum number of retry attempts",
    "default": 3,
    "min": 1,
    "max": 10,
    "step": 1
  },
  "timeout": {
    "type": "number",
    "label": "Timeout (seconds)",
    "default": 30,
    "min": 5,
    "max": 300
  }
}

Boolean

{
  "enabled": {
    "type": "boolean",
    "label": "Enable Feature",
    "default": true
  },
  "debugMode": {
    "type": "boolean",
    "label": "Debug Mode",
    "description": "Enable verbose logging",
    "default": false
  }
}

Select

{
  "environment": {
    "type": "select",
    "label": "Environment",
    "default": "production",
    "options": [
      { "value": "development", "label": "Development" },
      { "value": "staging", "label": "Staging" },
      { "value": "production", "label": "Production" }
    ]
  }
}

Multi-Select

{
  "features": {
    "type": "multiselect",
    "label": "Enabled Features",
    "default": ["logging"],
    "options": [
      { "value": "logging", "label": "Logging" },
      { "value": "caching", "label": "Caching" },
      { "value": "compression", "label": "Compression" },
      { "value": "rate-limiting", "label": "Rate Limiting" }
    ]
  }
}

Field Properties

Property	Type	Description
type	string	Field type (required)
label	string	Display label (required)
description	string	Help text
default	any	Default value
required	boolean	Is required
secret	boolean	Hide value, encrypt storage
placeholder	string	Input placeholder
validation	string	Validation rule
options	array	Options for select types
min	number	Minimum value
max	number	Maximum value
step	number	Step increment
group	string	Settings group
dependsOn	object	Conditional visibility

Validation Rules

Built-in Rules

{
  "email": {
    "type": "string",
    "validation": "email"
  },
  "url": {
    "type": "string",
    "validation": "url"
  },
  "slug": {
    "type": "string",
    "validation": "slug"
  }
}

Custom Regex

{
  "apiKey": {
    "type": "string",
    "validation": "regex:^sk_[a-zA-Z0-9]{24}$",
    "validationMessage": "Must be a valid API key starting with sk_"
  }
}

Grouping Settings

Organize settings into groups:

{
  "settings": {
    "groups": [
      { "id": "general", "label": "General" },
      { "id": "advanced", "label": "Advanced" },
      { "id": "notifications", "label": "Notifications" }
    ],
    "schema": {
      "enabled": {
        "type": "boolean",
        "label": "Enable Plugin",
        "group": "general"
      },
      "apiKey": {
        "type": "string",
        "label": "API Key",
        "group": "general"
      },
      "debugMode": {
        "type": "boolean",
        "label": "Debug Mode",
        "group": "advanced"
      },
      "emailNotifications": {
        "type": "boolean",
        "label": "Email Notifications",
        "group": "notifications"
      }
    }
  }
}

Conditional Settings

Show/hide settings based on other values:

{
  "useCustomEndpoint": {
    "type": "boolean",
    "label": "Use Custom Endpoint",
    "default": false
  },
  "customEndpoint": {
    "type": "string",
    "label": "Custom Endpoint URL",
    "validation": "url",
    "dependsOn": {
      "field": "useCustomEndpoint",
      "value": true
    }
  }
}

Complex Conditions

{
  "provider": {
    "type": "select",
    "label": "Provider",
    "options": [
      { "value": "stripe", "label": "Stripe" },
      { "value": "paypal", "label": "PayPal" }
    ]
  },
  "stripeKey": {
    "type": "string",
    "label": "Stripe API Key",
    "secret": true,
    "dependsOn": {
      "field": "provider",
      "value": "stripe"
    }
  },
  "paypalClientId": {
    "type": "string",
    "label": "PayPal Client ID",
    "dependsOn": {
      "field": "provider",
      "value": "paypal"
    }
  }
}

Secret Settings

Sensitive values are encrypted and hidden:

{
  "apiKey": {
    "type": "string",
    "label": "API Key",
    "secret": true,
    "required": true
  },
  "webhookSecret": {
    "type": "string",
    "label": "Webhook Secret",
    "secret": true
  }
}

In the admin UI:

• Values display as ••••••••
• Stored encrypted in database
• Never exposed in client-side code

Environment Variable Mapping

Map settings to environment variables:

{
  "settings": {
    "schema": {
      "apiKey": {
        "type": "string",
        "label": "API Key",
        "envVar": "MY_PLUGIN_API_KEY"
      }
    }
  }
}

Generated .env.example:

MY_PLUGIN_API_KEY=your-api-key-here

Accessing Settings

In Generator

export default async function generate(context) {
  const { settings } = context;

  console.log(settings.apiKey);
  console.log(settings.enabled);
}

In Runtime Code

// Generated by AutoDeployBase
import { getPluginSettings } from '@/lib/settings';

const settings = await getPluginSettings('my-plugin');
console.log(settings.apiKey);

In Templates

templates/lib/client.ts

const API_URL = '{{settings.apiUrl}}';
const MAX_RETRIES = {{settings.maxRetries}};

export async function fetchData() {
  let retries = 0;
  while (retries < MAX_RETRIES) {
    try {
      return await fetch(API_URL);
    } catch (error) {
      retries++;
    }
  }
}

Complete Example

manifest.json

{
  "name": "email-notifications",
  "version": "1.0.0",
  "settings": {
    "groups": [
      { "id": "provider", "label": "Email Provider" },
      { "id": "templates", "label": "Email Templates" },
      { "id": "advanced", "label": "Advanced" }
    ],
    "schema": {
      "provider": {
        "type": "select",
        "label": "Email Provider",
        "group": "provider",
        "default": "resend",
        "options": [
          { "value": "resend", "label": "Resend" },
          { "value": "sendgrid", "label": "SendGrid" },
          { "value": "mailgun", "label": "Mailgun" },
          { "value": "smtp", "label": "SMTP" }
        ]
      },
      "apiKey": {
        "type": "string",
        "label": "API Key",
        "group": "provider",
        "secret": true,
        "required": true,
        "envVar": "EMAIL_API_KEY",
        "dependsOn": {
          "field": "provider",
          "value": ["resend", "sendgrid", "mailgun"]
        }
      },
      "smtpHost": {
        "type": "string",
        "label": "SMTP Host",
        "group": "provider",
        "dependsOn": { "field": "provider", "value": "smtp" }
      },
      "smtpPort": {
        "type": "number",
        "label": "SMTP Port",
        "group": "provider",
        "default": 587,
        "dependsOn": { "field": "provider", "value": "smtp" }
      },
      "fromEmail": {
        "type": "string",
        "label": "From Email",
        "group": "templates",
        "validation": "email",
        "required": true,
        "default": "noreply@example.com"
      },
      "fromName": {
        "type": "string",
        "label": "From Name",
        "group": "templates",
        "default": "My App"
      },
      "replyTo": {
        "type": "string",
        "label": "Reply-To Email",
        "group": "templates",
        "validation": "email"
      },
      "rateLimit": {
        "type": "number",
        "label": "Rate Limit (per minute)",
        "group": "advanced",
        "default": 100,
        "min": 1,
        "max": 1000
      },
      "retryAttempts": {
        "type": "number",
        "label": "Retry Attempts",
        "group": "advanced",
        "default": 3,
        "min": 0,
        "max": 5
      },
      "debugMode": {
        "type": "boolean",
        "label": "Debug Mode",
        "group": "advanced",
        "description": "Log all email operations",
        "default": false
      }
    }
  }
}