Creating an Extension

This guide covers the full process of creating a Klyx extension, from project setup to advanced features like screens, toolbar actions, and file openers.

Project structure

A well-organized extension looks like this:

my-extension/
├── app/
│   ├── build.gradle.kts
│   └── src/main/
│       ├── AndroidManifest.xml
│       └── java/com/myext/
│           ├── MyExtension.kt        # Plugin entry class
│           └── ui/
│               ├── MainScreen.kt     # Custom screens
│               └── DetailScreen.kt
├── build.gradle.kts
├── settings.gradle.kts
├── gradle/libs.versions.toml
└── plugin.json                       # Plugin manifest

The entry class

Your extension’s entry point is a class that implements KlyxPlugin. Klyx discovers this class through the entryClass field in plugin.json and loads it reflectively.

MyExtension.kt

class MyExtension : KlyxPlugin {

    private val screens: ScreenRegistry by plugin()
    private val toolbar: ToolbarRegistry by plugin()
    private val navigator: Navigator by plugin()
    private val info: PluginInfo by runtime()

    override suspend fun onLoad() {
        // Register screens and toolbar actions
        screens.register(this, Screen(ScreenId("myext.main")) {
            MainScreen(navigator)
        })
        toolbar.register(this, ToolbarAction(
            id = "myext.show_main",
            label = "My Extension",
            icon = ToolbarIcon(Icons.Default.Extension),
            category = ToolbarCategory("My Plugin"),
            priority = 100,
            onClick = { navigator.navigateTo(NavDestination.Custom(ScreenId("myext.main"))) }
        ))
    }

    override suspend fun onStart() {
        // All plugins loaded — safe to interact
    }

    override suspend fun onStop() {
        // Release resources acquired in onStart
    }

    override suspend fun onUnload() {
        // Cleanup — unregister everything
        screens.unregister(ScreenId("myext.main"))
        toolbar.unregister("myext.show_main")
    }
}

Registering resources

Screens

screens.register(this, Screen(ScreenId("myext.detail")) {
    DetailScreen()
})

Add actions to Klyx’s toolbar. Each action has an ID, label, icon, category, priority, and click handler. Higher priority values place the action first.

toolbar.register(this, ToolbarAction(
    id = "myext.action1",
    label = "Do Something",
    icon = ToolbarIcon.Resource("action.png"),
    category = ToolbarCategory("My Plugin"),
    priority = 100,
    onClick = { /* handle action */ }
))

File openers

Register a FileOpener to handle custom file types. The opener returns a WorkspaceTab if it can handle the file, or null to let other openers try.

openers.register(object : FileOpener {
    override val id = "myext.opener"
    override val priority = 50
    override suspend fun open(request: FileOpenRequest): WorkspaceTab? {
        if (request.extension != "svg") return null
        return WorkspaceTab.Custom(
            title = request.fileName,
            content = { SvgViewer(request.uri) }
        )
    }
})

Responding to events

Use the event bus to react to app events. Subscribe in onLoad() and unsubscribe in onUnload().

override suspend fun onLoad() {
    val bus = currentPluginContext().eventBus
    job = pluginScope.launch {
        bus.subscribe(FileOpenedEvent::class) { event ->
            showToast("File opened: ${event.fileName}")
        }
    }
}

override suspend fun onUnload() {
    job?.cancel()
}

See Events for all available event types. Use the Navigator service to navigate users to different destinations:

navigator.navigateTo(NavDestination.Home)
navigator.navigateTo(NavDestination.Settings)
navigator.navigateTo(NavDestination.Terminal)
navigator.navigateTo(NavDestination.Custom(ScreenId("myext.main")))
navigator.navigateBack()

Best practices

Keep onLoad() fast: Defer heavy work to onStart() or launch a coroutine
Unregister everything: Always clean up screens, toolbar actions, and subscribers in onUnload()
Handle file openers gracefully: Return null from open() if you can’t handle the file
Use pluginScope: Launch long-running coroutines on pluginScope so they’re properly cancelled

Getting Started

Extension Development

API References

Creating an Extension

Project structure

The entry class

Registering resources

Screens

File openers

Responding to events

Navigation

Best practices

​Project structure

​The entry class

​Registering resources

​Screens

​Toolbar actions

​File openers

​Responding to events

​Navigation

​Best practices

Project structure

The entry class

Registering resources

Screens

Toolbar actions

File openers

Responding to events

Navigation

Best practices