My First Addon

A comprehensive demo addon for GitCaddy that showcases all available addon features and APIs.

Overview

This addon demonstrates:

• Addon Manifest (addon.json) - How to define your addon's metadata, permissions, and contributions
• Main Process Module (main/index.js) - Lifecycle methods, IPC, settings, and method invocations
• Renderer Process Module (renderer/index.js) - UI components and renderer-side communication
• Custom Views - HTML-based views for repository panels and settings
• Shared Types - Code shared between main and renderer processes

Project Structure

myfirst-addon/
├── addon.json           # Addon manifest (required)
├── main/
│   └── index.js         # Main process module (required)
├── renderer/
│   └── index.js         # Renderer process module (optional)
├── shared/
│   └── types.js         # Shared constants and types
├── views/
│   ├── demo.html        # Demo repository view
│   └── settings.html    # Settings panel view
└── README.md            # This file

Addon Manifest (addon.json)

The manifest defines everything about your addon:

Required Fields

Field	Description
id	Unique identifier (reverse domain notation: com.yourcompany.addon-name)
name	Display name shown in Addon Manager
version	Semantic version (major.minor.patch)
minAppVersion	Minimum GitCaddy version required
description	Short description for the addon list
main	Path to main process JavaScript module

Optional Fields

Field	Description
renderer	Path to renderer process module for UI components
author	Author information (name, email, url)
host	Native host configuration for .NET/Go/Rust addons
permissions	Required permissions (shown to user before install)
capabilities	What your addon can do
contributes	UI elements your addon adds

Permissions

"permissions": [
  "repository:read",     // Read repository data
  "repository:write",    // Modify repository
  "diff:read",           // Read diff/changes
  "commit:read",         // Read commit history
  "branch:read",         // Read branch information
  "network:localhost",   // Make local network requests
  "network:external",    // Make external network requests
  "settings:store",      // Store addon settings
  "notifications:show"   // Show notifications
]

Capabilities

"capabilities": [
  "commit-message-generation",  // Can generate commit messages
  "repository-analysis",        // Can analyze repositories
  "custom-view"                 // Has custom UI views
]

Main Process Module

The main module handles:

Lifecycle Methods

class MyAddon {
  // Called once when addon is loaded
  async initialize(context) { }

  // Called when addon is enabled
  async activate() { }

  // Called when addon is disabled
  async deactivate() { }

  // Called when addon is unloaded
  dispose() { }
}

Context Object

The context object provides:

context.addonId       // Your addon's ID
context.addonPath     // Path to addon directory
context.manifest      // Parsed addon.json
context.log           // Logger (.debug, .info, .warn, .error)
context.settings      // Settings storage
context.events        // Event emitter
context.ipc           // IPC communication
context.appState      // Access to app state
context.hostPort      // Port of native host (if configured)

Invoke Method

GitCaddy calls your addon's invoke method for all actions:

async invoke(method, args) {
  switch (method) {
    case 'myAction':
      return this.myAction(args[0], args[1]);
    default:
      throw new Error(`Unknown method: ${method}`);
  }
}

Contributions

Toolbar Buttons

{
  "id": "my-button",
  "tooltip": "Button Tooltip",
  "icon": { "type": "octicon", "value": "rocket" },
  "position": "after-push-pull",
  "onClick": {
    "action": "show-view",
    "target": "my-view"
  },
  "badge": {
    "method": "getBadgeContent"
  }
}

Position options: start, end, after-push-pull, after-branch

Menu Items

{
  "id": "my-menu-item",
  "menu": "repository",
  "label": "My Action",
  "accelerator": "CmdOrCtrl+Shift+M",
  "onClick": {
    "action": "invoke-method",
    "method": "menuAction"
  }
}

Repository Views

{
  "id": "my-view",
  "title": "My View",
  "icon": "rocket",
  "renderer": {
    "type": "iframe",
    "source": "views/my-view.html"
  },
  "context": ["repository"]
}

Context options: repository, diff, commit, always

Context Menu Items

{
  "id": "file-action",
  "context": "file-list",
  "label": "Process Files",
  "onClick": {
    "action": "invoke-method",
    "method": "processFiles"
  }
}

Context options: file-list, commit-list

Settings Definitions

{
  "key": "enableFeature",
  "type": "boolean",
  "default": true,
  "description": "Enable the main feature"
}

Types: boolean, string, number, select

View Communication

Views communicate with the addon via the window.gitcaddy bridge:

// Wait for bridge to be ready
if (window.gitcaddy) {
  init();
} else {
  window.addEventListener('gitcaddy-ready', init);
}

// Invoke addon methods
const result = await window.gitcaddy.invoke('myMethod', arg1, arg2);

// Send one-way messages
window.gitcaddy.send('my-channel', { data: 'value' });

// Listen for messages
window.gitcaddy.on('addon-message', (data) => {
  console.log('Received:', data);
});

// Logging
window.gitcaddy.log.info('Something happened');
window.gitcaddy.log.error('Something went wrong');

Native Hosts

For addons that need native code (.NET, Go, Rust, etc.):

"host": {
  "directory": "host",
  "executable": "MyAddon.Host",
  "platforms": {
    "win32-x64": "host/win-x64/MyAddon.Host.exe",
    "linux-x64": "host/linux-x64/MyAddon.Host",
    "darwin-x64": "host/darwin-x64/MyAddon.Host",
    "darwin-arm64": "host/darwin-arm64/MyAddon.Host"
  },
  "healthCheck": "/health",
  "startupTimeout": 15000
}

Communicate with your host via HTTP:

const response = await fetch(`http://127.0.0.1:${this.context.hostPort}/my-endpoint`);

Installation

For Development (Sideloading)

1. Copy this folder to GitCaddy's addons directory:

   • Windows: %APPDATA%/GitCaddy/addons/
   • macOS: ~/Library/Application Support/GitCaddy/addons/
   • Linux: ~/.config/GitCaddy/addons/

2. Restart GitCaddy or reload addons from the Addon Manager

For Distribution

Package your addon as a .zip file and distribute it. Users can install via:

• Addon Manager's "Install from file" option
• Dropping the zip into the addons directory

Tips

1. Use the logger - Always use context.log instead of console.log for proper addon logging
2. Handle errors - Wrap async operations in try/catch and log errors appropriately
3. Clean up - Always dispose of event listeners and resources in the dispose method
4. Secure API keys - Never expose API keys in logs or UI; use the hasApiKey pattern
5. Test on all platforms - If using native hosts, ensure they work on Windows, macOS, and Linux

Resources

• Octicons - Icon library for toolbar buttons
• GitCaddy Documentation - Full addon API documentation

License

MIT - Use this as a template for your own addons!