Best way to design a plugin-style architecture in Kotlin (JVM)

[Anuja122]

Hi everyone 👋
I’m developing a Kotlin (JVM) application and I’m trying to design a clean, extensible plugin architecture. I’d like some feedback on best practices and common pitfalls.

---

What I’m trying to do

I want to allow external modules (plugins) to extend my application by:

• Registering features or commands
• Interacting with a restricted public API
• Being discovered and loaded at runtime

Plugins will be distributed as JAR files and dropped into a plugins/ directory.

---

Current design

Right now, I’m using Java-style class loading from Kotlin:

val classLoader = URLClassLoader(
    arrayOf(pluginJar.toURI().toURL()),
    this::class.java.classLoader
)

val pluginClass = classLoader.loadClass("plugin.Main")
val plugin = pluginClass.getDeclaredConstructor().newInstance() as Plugin

plugin.onLoad(api)

This works, but I’m not sure if this is the right approach in idiomatic Kotlin.

---

Concerns

• ClassLoader-based plugins feel fragile
• No clear lifecycle management (load, enable, disable)
• Plugins can accidentally depend on internal classes
• Hard to version the plugin API safely
• Error handling is messy when a plugin fails during startup

---

Environment

• Language: Kotlin 1.9+
• Runtime: JVM (Java 17+)
• Build tool: Gradle (Kotlin DSL)
• Target: Desktop / CLI application

---

What I’ve considered

• ✔️ Explicit Plugin interface + lifecycle methods
• ✔️ Separate api module shared with plugins
• ✔️ Service discovery using ServiceLoader
• ❓ Dependency injection (Koin / Dagger / manual)
• ❓ Using scripting (Kotlin Script, JS, Lua) instead of JAR plugins
• ❓ Running plugins in isolated processes

---

Questions

1. What is the recommended way to implement plugins in Kotlin/JVM today?
2. Is ServiceLoader a better approach than manual ClassLoader usage?
3. How do you version a plugin API without constantly breaking plugins?
4. Are there good real-world examples of Kotlin-based plugin systems?
5. Should plugins be trusted, or is sandboxing realistically achievable on the JVM?

---

Goal

I want a plugin system that is:

• Idiomatic Kotlin
• Easy for third-party developers
• Stable across versions
• Maintainable long-term

Any architectural advice, examples, or references would be greatly appreciated 🙏
Thanks!

Guidelines

• I have read and understood this category's guidelines before making this post.

[AnujaGajaweera]

“What is the recommended way to implement plugins in Kotlin/JVM today?”

Short answer:
👉 Use a Java-compatible plugin model built around a shared API module + ServiceLoader, with explicit lifecycle management. Kotlin does not replace JVM fundamentals here—it builds on them.

---

🧠 Key Principle

Kotlin runs on the JVM, so the recommended approach is still:

Well-defined interfaces + controlled class loading + minimal reflection

Kotlin’s strengths (null safety, data classes, DSLs) help you design a clean API, but plugin loading itself remains a JVM concern.

---

🏗️ Recommended Architecture

1️⃣ Separate api module (critical)

Create a pure API module that both the host app and plugins depend on.

root
├── app
├── api
└── plugins

api module should contain only:

• Interfaces
• Data classes
• Stable enums
• No implementation logic

interface Plugin {
    val id: String
    fun onLoad(context: PluginContext)
    fun onEnable()
    fun onDisable()
}

This gives you:

• Binary compatibility
• Clear versioning
• No accidental internal access

---

2️⃣ Use ServiceLoader (recommended)

Instead of hardcoding class names, rely on standard JVM service discovery.

Plugin side

class MyPlugin : Plugin {
    override val id = "example"

    override fun onLoad(context: PluginContext) {}
    override fun onEnable() {}
    override fun onDisable() {}
}

META-INF/services/com.example.api.Plugin

com.example.plugin.MyPlugin

Host side

val loader = ServiceLoader.load(
    Plugin::class.java,
    pluginClassLoader
)

val plugins = loader.toList()

✔ No reflection hacks
✔ Idiomatic JVM
✔ Widely used (Gradle, Java SPI, IntelliJ, etc.)

---

3️⃣ ClassLoader isolation (but keep it simple)

Use one URLClassLoader per plugin.

val loader = URLClassLoader(
    arrayOf(pluginJar.toURI().toURL()),
    apiClassLoader // NOT the app classloader
)

This prevents:

• Class conflicts
• Plugins depending on app internals
• Accidental linkage errors

Kotlin adds zero value by replacing this with “fancy” abstractions—keep it explicit.

---

4️⃣ Explicit lifecycle management

Do not rely on constructors.

plugin.onLoad(context)
plugin.onEnable()

This allows:

• Validation before enable
• Clean error handling
• Future hot-reload support

---

🚫 What NOT to do

❌ Loading arbitrary classes by name
❌ Letting plugins access app classpath
❌ Reflection-heavy scanning
❌ Mixing plugin API + implementation
❌ Relying on Kotlin scripting for production plugins

---

🧩 Why this is considered “best practice”

This model is used by:

• Gradle
• IntelliJ Platform
• Minecraft (Fabric / Bukkit / Paper)
• OSGi-lite systems
• Most long-lived JVM tools

Kotlin improves developer ergonomics, not plugin isolation mechanics.

---

📌 Summary

Recommended Kotlin/JVM plugin approach:

✔ Shared api module
✔ ServiceLoader discovery
✔ One ClassLoader per plugin
✔ Explicit lifecycle
✔ Stable interfaces

This gives you:

• Maintainability
• Binary compatibility
• Idiomatic Kotlin + JVM correctness