Plugin Lifecycle

Understanding the Klyx plugin lifecycle

Klyx manages your extension through four lifecycle methods. Each method runs as a suspend function on the plugin’s coroutine scope, so you can safely call other suspend APIs.

Lifecycle overview

Load → onLoad() → onStart() → (running) → onStop() → onUnload() → Unloaded

Phase	Method	Purpose
1	onLoad()	Register resources, set up infrastructure
2	onStart()	Begin operations that depend on other plugins
3	onStop	(Triggered by user or system)
4	onStop()	Pause or release start-time resources
5	onUnload()	Full cleanup — unregister everything
6	Unloaded	Plugin removed from memory

onLoad()

Called when Klyx loads your extension. At this point, your plugin’s services (screens, toolbar, etc.) are available, but other plugins may not have started yet.

What to do here:

• Register screens with ScreenRegistry
• Register toolbar actions with ToolbarRegistry
• Subscribe to events on the event bus
• Register file openers
• Initialize lightweight state

override suspend fun onLoad() {
    screens.register(this, Screen(ScreenId("myext.main")) { MainScreen() })
    toolbar.register(this, ToolbarAction(
        id = "myext.action",
        label = "My Action",
        category = ToolbarCategory("My Plugin"),
        priority = 100,
        onClick = { /* ... */ }
    ))
}

onStart()

Called after all plugins have completed onLoad(). This is the right place to interact with other plugins, access shared resources, or start ongoing work.

What to do here:

• Register file openers (if they depend on other plugins)
• Start coroutines for background work
• Access other plugin’s registered resources

override suspend fun onStart() {
    // Register a file opener for a custom type
    openers.register(object : FileOpener {
        override val id = "myext.opener"
        override val priority = 50
        override suspend fun open(request: FileOpenRequest): WorkspaceTab? {
            if (request.extension != "mp3") return null
            return WorkspaceTab.Custom(title = request.fileName) {
                AudioPlayer(request.uri)
            }
        }
    })
}

onStop()

Called when Klyx is about to unload your extension. You should release any resources acquired in onStart().

What to do here:

• Cancel ongoing operations started in onStart()
• Close file handles or network connections
• Unregister file openers

override suspend fun onStop() {
    showToast("Stopping...")
}

onUnload()

Called after onStop() completes. This is your last chance to clean up before the plugin classloader is discarded.

What to do here:

• Unregister all screens
• Unregister all toolbar actions
• Cancel all coroutines
• Unsubscribe from events

override suspend fun onUnload() {
    screens.unregister(ScreenId("myext.main"))
    screens.unregister(ScreenId("myext.detail"))
    toolbar.unregister("myext.action")
    toolbar.unregister("myext.other_action")
    job?.cancel()
}

If you don’t unregister screens and toolbar actions in `onUnload()’, they will leak. Klyx does not automatically clean them up.

Using the plugin scope

Your plugin has access to a CoroutineScope via pluginScope or lifecycleOwner.lifecycleScope. Coroutines launched on this scope are automatically cancelled when the plugin is unloaded.

override suspend fun onLoad() {
    // This coroutine is tied to the plugin's lifecycle
    pluginScope.launch {
        // Background work
    }
}