Home/Documentation/Developers/Getting Started

Getting Started

Build your first Elysium plugin in under 10 minutes. This guide walks you through setup, development, and testing.

Prerequisites

macOS 14.0+
Elysium and its plugin system require macOS Sonoma or later.
Xcode 15+
Install from the Mac App Store or developer.apple.com.
Elysium installed
Download the latest version from elysium.is.
Swift 5.9+ knowledge
Plugins are written in Swift. Familiarity with Swift and SwiftUI helps.

Clone the Plugin Template

Start with our official plugin template. It includes the project structure, manifest file, and example code.

git clone https://github.com/elysiumis/plugin-template.git my-plugin
cd my-plugin

Replace my-plugin with your plugin name.

Configure Your Plugin

Open Plugin.swift and update the manifest with your plugin's information:

import ElysiumPluginKit

@main
struct MyPlugin: ElysiumPlugin {
    static let manifest = PluginManifest(
        id: "com.yourname.myplugin",
        name: "My Plugin",
        version: "1.0.0",
        description: "A brief description of what your plugin does.",
        author: "Your Name",
        minElysiumVersion: "1.0.0"
    )

    func onLoad() {
        // Called when the plugin is loaded
        print("My plugin loaded!")
    }

    func onUnload() {
        // Called when the plugin is unloaded
    }
}

Add Functionality

func onLoad() {
    // Register a command in the action menu
    registerCommand(
        Command(
            id: "my-plugin.hello",
            name: "Say Hello",
            icon: "hand.wave",
            action: { context in
                // Access the current schedule item
                if let item = context.selectedItem {
                    print("Hello from \(item.title)!")
                }
            }
        )
    )
}

Build and Test

Build your plugin and install it in Elysium's development plugins folder:

# Build the plugin
swift build -c release

# Copy to Elysium's dev plugins folder
cp -r .build/release/MyPlugin.bundle ~/Library/Application\ Support/Elysium/Plugins/Dev/

Tip: Enable Developer Mode in Elysium settings to see debug output and auto-reload plugins on file changes.

Share Your Plugin

When you're ready to share your plugin with the community:

Push your code to a public GitHub repository

Add a README with installation instructions and screenshots

Submit your plugin for review and inclusion in the community directory

Project Structure

my-plugin/
├── Package.swift           # Swift package manifest
├── Sources/
│   └── MyPlugin/
│       ├── Plugin.swift    # Main plugin entry point
│       ├── Commands/       # Custom commands
│       ├── Views/          # Custom SwiftUI views
│       └── Resources/      # Assets, localization
├── Tests/                  # Unit tests
└── README.md