SDK Reference

Complete API reference for the AutoDeployBase Plugin SDK.

Import

import { sdk } from 'autodeploybase';

Context Object

The context object passed to generators:

interface GeneratorContext {
  projectPath: string; // Absolute path to project
  projectName: string; // Project name
  framework: Framework; // Target framework
  database: Database; // Database type
  settings: PluginSettings; // Plugin settings from config
  config: ProjectConfig; // Full project configuration
}

type Framework = 'next' | 'nuxt' | 'sveltekit' | 'remix' | 'astro' | 'hono' | 'fresh' | 'react';
type Database = 'postgresql' | 'mongodb' | 'sqlite';

Core Functions

copyTemplates

Copy template files to the project with variable substitution.

sdk.copyTemplates(options: CopyTemplatesOptions): Promise<void>

interface CopyTemplatesOptions {
  source: string;           // Source directory (relative to plugin)
  destination: string;      // Destination directory
  framework?: Framework;    // Current framework
  variables?: Record<string, any>;  // Template variables
  ignore?: string[];        // Glob patterns to ignore
  overwrite?: boolean;      // Overwrite existing files (default: false)
}

Example:

await sdk.copyTemplates({
  source: './templates/next',
  destination: context.projectPath,
  variables: {
    pluginName: 'my-plugin',
    apiUrl: settings.apiUrl,
    enableDebug: settings.debug
  },
  ignore: ['**/*.test.ts', '**/__tests__/**']
});

registerAPIRoutes

Register API routes for the project.

sdk.registerAPIRoutes(options: RegisterRoutesOptions): Promise<void>

interface RegisterRoutesOptions {
  routes: APIRoute[];
}

interface APIRoute {
  path: string;             // Route path (e.g., '/api/users')
  handler?: string;         // Handler file path
  methods?: HTTPMethod[];   // Allowed methods
  middleware?: string[];    // Middleware to apply
}

type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

Example:

await sdk.registerAPIRoutes({
  routes: [
    {
      path: '/api/my-plugin',
      handler: 'plugins/my-plugin/api/route',
      methods: ['GET', 'POST']
    },
    {
      path: '/api/my-plugin/:id',
      handler: 'plugins/my-plugin/api/[id]/route',
      methods: ['GET', 'PUT', 'DELETE'],
      middleware: ['auth']
    }
  ]
});

registerAdminMenu

Add items to the admin sidebar.

sdk.registerAdminMenu(options: AdminMenuOptions): Promise<void>

interface AdminMenuOptions {
  id: string;               // Unique identifier
  label: string;            // Display label
  icon?: string;            // Lucide icon name
  href?: string;            // Link URL
  order?: number;           // Sort order (default: 100)
  children?: AdminMenuOptions[];  // Submenu items
  permission?: string;      // Required permission
}

Example:

await sdk.registerAdminMenu({
  id: 'my-plugin',
  label: 'My Plugin',
  icon: 'Plug',
  order: 50,
  children: [
    {
      id: 'my-plugin-dashboard',
      label: 'Dashboard',
      href: '/admin/my-plugin'
    },
    {
      id: 'my-plugin-settings',
      label: 'Settings',
      href: '/admin/my-plugin/settings',
      permission: 'admin'
    }
  ]
});

registerPrismaSchema

Add database models to the Prisma schema.

sdk.registerPrismaSchema(schema: string): Promise<void>

Example:

await sdk.registerPrismaSchema(`
  model Notification {
    id        String   @id @default(cuid())
    userId    String
    user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
    type      NotificationType
    title     String
    message   String
    data      Json?
    read      Boolean  @default(false)
    createdAt DateTime @default(now())
    
    @@index([userId])
    @@index([read])
  }
  
  enum NotificationType {
    INFO
    WARNING
    ERROR
    SUCCESS
  }
`);

registerSettings

Define plugin settings schema.

sdk.registerSettings(options: RegisterSettingsOptions): Promise<void>

interface RegisterSettingsOptions {
  pluginId: string;
  schema: SettingsSchema;
}

interface SettingsSchema {
  [key: string]: SettingField;
}

interface SettingField {
  type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect';
  label: string;
  description?: string;
  default?: any;
  required?: boolean;
  secret?: boolean;         // Hide in UI, encrypt in storage
  validation?: string;      // 'email' | 'url' | 'regex:pattern'
  options?: SelectOption[]; // For select/multiselect
  min?: number;             // For number type
  max?: number;             // For number type
}

interface SelectOption {
  value: string;
  label: string;
}

Example:

await sdk.registerSettings({
  pluginId: 'my-plugin',
  schema: {
    enabled: {
      type: 'boolean',
      label: 'Enable Plugin',
      default: true
    },
    apiKey: {
      type: 'string',
      label: 'API Key',
      required: true,
      secret: true
    },
    environment: {
      type: 'select',
      label: 'Environment',
      default: 'production',
      options: [
        { value: 'development', label: 'Development' },
        { value: 'staging', label: 'Staging' },
        { value: 'production', label: 'Production' }
      ]
    },
    maxRetries: {
      type: 'number',
      label: 'Max Retries',
      default: 3,
      min: 1,
      max: 10
    },
    webhookUrl: {
      type: 'string',
      label: 'Webhook URL',
      validation: 'url'
    }
  }
});

registerProvider

Register React context providers.

sdk.registerProvider(options: ProviderOptions): Promise<void>

interface ProviderOptions {
  name: string;             // Provider component name
  import: string;           // Import path
  order?: number;           // Nesting order (lower = outer)
  props?: Record<string, any>;  // Props to pass
}

Example:

await sdk.registerProvider({
  name: 'NotificationProvider',
  import: '@/plugins/notifications/provider',
  order: 20,
  props: {
    maxVisible: 5
  }
});

registerCSS

Register CSS variables.

sdk.registerCSS(options: CSSOptions): Promise<void>

interface CSSOptions {
  variables?: Record<string, string>;
  imports?: string[];
}

Example:

await sdk.registerCSS({
  variables: {
    '--notification-bg': '#ffffff',
    '--notification-text': '#1a1a1a',
    '--notification-success': '#10b981',
    '--notification-error': '#ef4444',
    '--notification-warning': '#f59e0b'
  },
  imports: ['@/plugins/notifications/styles.css']
});

Utility Functions

detectFramework

Detect the current framework from project files.

sdk.detectFramework(projectPath: string): Promise<Framework | null>

getFrameworkHelpers

Get framework-specific utilities.

sdk.getFrameworkHelpers(framework: Framework): FrameworkHelpers

interface FrameworkHelpers {
  routeFilePattern: string;
  componentExtension: string;
  apiRoutePattern: string;
  getLayoutPath: () => string;
  getApiRoutePath: (route: string) => string;
}

Example:

const helpers = sdk.getFrameworkHelpers(context.framework);

// Next.js: 'src/app/api/my-route/route.ts'
// Nuxt: 'server/api/my-route.ts'
const apiPath = helpers.getApiRoutePath('/api/my-route');

validateSettings

Validate plugin settings against schema.

sdk.validateSettings(settings: any, schema: SettingsSchema): ValidationResult

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
}

generateExports

Generate export file for plugin.

sdk.generateExports(options: ExportOptions): Promise<void>

interface ExportOptions {
  pluginId: string;
  exports: Export[];
}

interface Export {
  name: string;
  path: string;
  type?: 'default' | 'named';
}

File Utilities

readTemplate

Read and process a template file.

sdk.readTemplate(path: string, variables: Record<string, any>): Promise<string>

writeFile

Write a file with automatic directory creation.

sdk.writeFile(path: string, content: string): Promise<void>

fileExists

Check if a file exists.

sdk.fileExists(path: string): Promise<boolean>

readJson

Read and parse a JSON file.

sdk.readJson<T>(path: string): Promise<T>

writeJson

Write an object as JSON.

sdk.writeJson(path: string, data: any, options?: { pretty?: boolean }): Promise<void>

Error Handling

import { sdk, PluginError } from 'autodeploybase';

export default async function generate(context) {
  try {
    await sdk.copyTemplates({ ... });
  } catch (error) {
    if (error instanceof PluginError) {
      console.error(`Plugin error: ${error.code} - ${error.message}`);
    }
    throw error;
  }
}

Error Codes

Code	Description
TEMPLATE_NOT_FOUND	Template file doesn't exist
INVALID_SETTINGS	Settings validation failed
FRAMEWORK_NOT_SUPPORTED	Plugin doesn't support framework
SCHEMA_CONFLICT	Prisma schema conflict
PERMISSION_DENIED	File permission error