Create a Plugin

The IDAH Plugin Generator is a CLI tool that helps you quickly scaffold new plugins with frontend and optional backend components for the IDAH platform.

Installation

Quick start using npx

The easiest way to use the plugin generator is with npx, which doesn't require any installation:

# Create a plugin npx idah-plugin create audio-plugin ./plugins # Add backend to existing plugin in ./plugins
        directory npx idah-plugin backend add audio-plugin ./plugins # Get help npx idah-plugin --help

Local Development with npm link

For local development and testing, use npm link:

cd plugins_dev npm install npm link

This creates a symlink in your global node_modules. You can now use the idah-plugin command from anywhere, and changes to the source code will be immediately available.

To unlink when you're done:

npm unlink -g idah-plugin

Global Installation

Install the CLI globally:

# From npm (after publishing) npm install -g idah-plugin # Or from local directory cd plugins_dev npm install
        -g .

After installation, you can use the idah-plugin command from any directory.

Direct Usage (Without Installation)

If you prefer not to install at all:

cd plugins_dev npm install node _cli/bin/cli.js <command>

Create a New Plugin

Create a new plugin from scratch:

idah-plugin create <plugin_name> [output_path]

Examples:

# Create in current directory idah-plugin create my-awesome-plugin # Creates: ./my-awesome-plugin # Create in
        specific directory idah-plugin create audio-plugin ./plugins # Creates: ./plugins/audio-plugin # Create with
        absolute path idah-plugin create video-plugin /path/to/plugins # Creates: /path/to/plugins/video-plugin

What happens when you create a plugin:

1. Prompts you for a display name (user-friendly name shown in the UI)
2. Prompts you for a description (brief description of your plugin)
3. Prompts you for a version (semantic version, default: 0.0.1)
4. Asks which backend services you want to include (media, sync, or none)
5. Generates the complete plugin structure in the specified location

Parameters:

• <plugin_name> - (Required) Name of the plugin in kebab-case
• [output_path] - (Optional) Directory where the plugin should be created (default: current directory)

Add Backend Services to Existing Plugin

Add one or more backend services to an existing plugin:

idah-plugin backend add <plugin_name> [base_path]

Examples:

# Add backend to plugin in current directory idah-plugin backend add my-awesome-plugin # Looks for:
        ./my-awesome-plugin # Add backend to plugin in specific directory idah-plugin backend add audio-plugin ./plugins
        # Looks for: ./plugins/audio-plugin

Parameters:

• <plugin_name> - (Required) Name of the plugin
• [base_path] - (Optional) Directory containing the plugin (default: current directory)

What happens when you add backends:

1. Checks if the plugin exists at the specified location
2. Prompts you to select which backend service(s) to add
3. Copies the backend templates and configures them for your plugin
4. Skips any backend services that already exist

Output location: The new backend(s) will be added to <plugin_name>/backends/<backend_service>/

For example:

• Adding "media" service → <plugin_name>/backends/media/
• Adding "sync" service → <plugin_name>/backends/sync/

Plugin Structure

When you create a plugin, the following high-level structure is generated:

<plugin_name>/
   ├─ README.md              # Plugin overview and quick start
   ├─ manifest.json          # Plugin metadata and configuration
   ├─ Gemfile                # Ruby dependencies (for backends)
   ├─ Rakefile               # Build and test tasks
   ├─ .gitignore
   ├─ .rspec
   ├─ backends/              # Backend services (optional)
   │  ├─ README.md              # Backend quick start guide
   │  ├─ media/                 # Media processing service (if selected)
   │  └─ sync/                  # Data export/sync service (if selected)
   └─ frontend/              # Frontend SvelteKit application
      ├─ README.md              # Frontend quick start guide
      ├─ package.json
      └─ src/                   # Source code

Key Files:

• manifest.json - Contains plugin metadata and configuration
• backends/ - Optional backend services for server-side functionality
• frontend/ - SvelteKit application for the plugin UI

Workflow Examples

Example 1: Create a Frontend-Only Plugin

# Create a new plugin in the plugins directory (recommended) idah-plugin create ui-widget ./plugins # When
        prompted: # - Display name: UI Widget # - Description: A simple UI widget plugin # - Version: 0.0.1 (or press
        Enter for default) # - Backend services: (press Enter without selecting any) # Your plugin is ready at
        ./plugins/ui-widget/ cd plugins/ui-widget/frontend pnpm install pnpm dev

Example 2: Create a Full-Stack Plugin

# Create a plugin with both backend services in plugins directory idah-plugin create video-converter ./plugins
        # When prompted: # - Display name: Video Converter # - Description: Convert videos to different formats # -
        Version: 1.0.0 # - Backend services: Select both "Media Service" and "Sync Service" # Your plugin is ready with
        backend and frontend cd plugins/video-converter

Example 3: Create Multiple Plugins

# Create several plugins in the standard plugins directory idah-plugin create image-gallery ./plugins
        idah-plugin create data-exporter ./plugins idah-plugin create custom-dashboard ./plugins # All plugins will be
        in ./plugins/ and automatically loaded by IDAH

Example 4: Add Backend to Existing Plugin

# First create a frontend-only plugin idah-plugin create image-processor ./plugins # Later, add backend
        services (specify base path where plugin is located) idah-plugin backend add image-processor ./plugins # When
        prompted, select "Media Service" # The media backend is now added to your existing plugin at
        ./plugins/image-processor

Plugin Naming Conventions

• Plugin name (CLI argument): Use kebab-case (e.g., my-awesome-plugin)
• Display name (prompts): Use human-readable format (e.g., My Awesome Plugin)
• Module name (generated): PascalCase (e.g., MyAwesomePlugin)
• Ruby filename (generated): snake_case (e.g., my_awesome_plugin.rb)

Troubleshooting

Plugin already exists

If you see an error that the plugin already exists, either:

• Choose a different name
• Delete the existing plugin directory first
• Use backend add to add services to the existing plugin

Backend service already exists

When using backend add, if a service already exists, it will be skipped automatically. You'll see an informational message.

Permission errors

If you get permission errors during global installation:

sudo npm install -g . # or use a Node version manager like nvm

Next Steps

After creating your plugin, learn how to develop its components:

• Frontend Guide - Build the plugin UI with SvelteKit
• Backend Guide - Develop backend services in Ruby
• Import & Process Media - Add media processing capabilities
• Export Datasets - Create data exporters