Modules

Ktor allows you to use modules to structure your application by defining a specific set of routes inside a specific module. A module is an extension function on Application that sets up routes, installs plugins, and configures services. Using modules helps you:

Group related routes and logic together.
Keep features or domains isolated.
Enable easier testing and modular deployment.

Defining a module

A module is an extension function of the Application class. In the example below, the module1 extension function defines a module that accepts GET requests made to the /module1 URL path.

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module1() {
    routing {
        get("/module1") {
            call.respondText("Hello from 'module1'!")
        }
    }
}

Loading modules in your application depends on the way used to create a server: in code using the embeddedServer function or by using the application.conf configuration file.

Loading modules

Embedded server

Typically, the embeddedServer function accepts a module implicitly as a lambda argument. You can see the example in the Configuration in code section. You can also extract application logic into a separate module and pass a reference to this module as the module parameter:

package com.example

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main() {
    embeddedServer(Netty, port = 8080, module = Application::module).start(wait = true)
}

fun Application.module() {
    module1()
    module2()
}

fun Application.module1() {
    routing {
        get("/module1") {
            call.respondText("Hello from 'module1'!")
        }
    }
}

fun Application.module2() {
    routing {
        get("/module2") {
            call.respondText("Hello from 'module2'!")
        }
    }
}

You can find the full example here: embedded-server-modules.

Configuration file

If you use the application.conf or application.yaml file to configure a server, you need to specify modules to load using the ktor.application.modules property.

Suppose you have three modules defined in two packages: two modules in the com.example package and one in the org.sample package.

package com.example

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

fun Application.module1() {
    routing {
        get("/module1") {
            call.respondText("Hello from 'module1'!")
        }
    }
}

fun Application.module2() {
    routing {
        get("/module2") {
            call.respondText("Hello from 'module2'!")
        }
    }
}

package org.sample

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module3() {
    routing {
        get("/module3") {
            call.respondText("Hello from 'module3'!")
        }
    }
}

To reference these modules in a configuration file, you need to provide their fully qualified names. A fully qualified module name includes a fully qualified name of the class and an extension function name.

ktor {
    application {
        modules = [ com.example.ApplicationKt.module1,
                    com.example.ApplicationKt.module2,
                    org.sample.SampleKt.module3 ]
    }
}

ktor:
    application:
        modules:
            - com.example.ApplicationKt.module1
            - com.example.ApplicationKt.module2
            - org.sample.SampleKt.module3

You can find the full example here: engine-main-modules.

Module dependencies

Modules often need to share common services, repositories, or configuration. Injecting dependencies rather than creating them inside a module improves testability and flexibility. Ktor offers several approaches depending on the complexity of your project.

Passing dependencies through parameters

The simplest way to pass dependencies is to declare them as parameters of module functions:

fun main() {
    embeddedServer(CIO, port = 8080, host = "0.0.0.0") {
        // Instantiate your dependency
        val myService = MyService(property<MyServiceConfig>())
        // Inject it into your modules as a parameter
        routingModule(myService)
        schedulingModule(myService)
    }.start(wait = true)
}

This works well for small or medium applications and keeps dependencies clear. However, modules become tightly coupled at compile time and cannot be easily swapped at runtime.

Using application attributes

You can use Application.attributes - a type-safe map available to all modules:

val customerServiceKey = AttributeKey<CustomerService>("CustomerService")

fun Application.servicesModule() {
    attributes[customerServiceKey] = CustomerService()
}

fun Application.customerModule() {
    val service = attributes[customerServiceKey]
    routing {
        get("/customers") { call.respond(service.all()) }
    }
}

This creates loose coupling by avoiding direct references between modules.

Using dependency injection

Ktor includes a dependency injection (DI) plugin, which allows you to declare and resolve dependencies directly inside your Ktor application using a lightweight container.

Concurrent modules

You can use suspendable functions when creating application modules. They allow events to run asynchronously when starting the application. To do that, add the suspend keyword:

suspend fun Application.installEvents() {
    val kubernetesConnection = connect(property<KubernetesConfig>("app.events"))
}

You can also launch all application modules independently, so when one is suspended, the others are not blocked. This allows for non-sequential loading for dependency injection and, in some cases, faster loading.

Configuration options

The following configuration properties are available:

Property	Type	Description	Default
`ktor.application.startup`	`sequential`/`concurrent`	Defines how application modules are loaded	`sequential`
`ktor.application.startupTimeoutMillis`	`Long`	Timeout for application module loading (in milliseconds)	`10000`

Enable concurrent module loading

To opt into concurrent module loading, add the following to your server configuration file:

# application.conf

ktor {
    application {
        startup = concurrent
    }
}

For dependency injection, you can load the following modules in order of appearance without issues:

suspend fun Application.installEvents() {
    // Suspends until provided
    val kubernetesConnection = dependencies.resolve<KubernetesConnection>()
}

suspend fun Application.loadEventsConnection() {
    dependencies.provide<KubernetesConnection> {
        connect(property<KubernetesConfig>("app.events"))
    }
}

23 January 2026