Create, open, and run a new Ktor project

1. Navigate to the Ktor project generator.

2. In the Project artifact field, enter com.example.ktor-sample as the name of your project artifact.

   

3. Click Configure to open the settings dropdown menu:

   

   The following settings are available:

   • Build System: Choose the desired build system. This can be Gradle Kotlin, Gradle Groovy, Maven, or Amper.

   • Use version catalog: Select this option to use a version catalog (libs.versions.toml) for managing dependency versions in Gradle and Amper projects. Requires Gradle 7 or later.

   • Ktor version: Choose the required Ktor version.

   • Engine: Select an engine used to run a server.

   • Configuration: Choose whether to specify server parameters in a YAML or HOCON file, or in code.

   • Include samples: Leave this option enabled to add sample code for plugins.

   For this tutorial, you can leave the default values for these settings.

4. Click Done to save the configuration and close the menu.

5. Below you will find a set of plugins that you can add to your project. Plugins are building blocks that provide common functionality in a Ktor application, such as authentication, serialization and content encoding, compression, cookie support, and more.

   For the sake of this tutorial, you don’t need to add any plugins at this stage.

6. Click the Download button to generate and download your Ktor project.

   

Your download should start automatically.

To run the project from within IntelliJ IDEA:

1. Open the Gradle tool window by clicking the Gradle icon () on the right sidebar.

2. Within this tool window, navigate to Tasks | application and double-click on the run task.

   

3. Your Ktor application starts in the Run tool window at the bottom of the IDE:

   

   The same messages that were previously displayed on the command line will now be visible in the Run tool window.

4. To confirm the project is running, open your browser at the specified URL (http://0.0.0.0:8080).

   You should once again see the message "Hello World!" displayed on the screen:

   

1. Open the Application.kt file and find the .configureRouting() function.

2. In IntelliJ IDEA, hold Ctrl (Windows/Linux) or ⌘Cmd (macOS) and click .configureRouting() to navigate to its definition.

   Alternatively, you can navigate to the function definition by opening the Routing.kt file.

   This is the code you should see:

   fun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } } }

3. To create a new endpoint, insert the additional route as shown below:

   fun Application.configureRouting() { routing { // ... get("/test1") { val text = "<h1>Hello From Ktor</h1>" val type = ContentType.parse("text/html") call.respondText(text, type) } } }

4. The IDE automatically adds the import for ContentType:

   import io.ktor.http.ContentType

5. Click on the rerun button () to restart the application.

6. Request the new URL in the browser (http://0.0.0.0:9292/test1). The port number depends on whether you completed the Change the default port task. You should see the output displayed below:

   

   If you have created an HTTP request file, you can also verify the new endpoint there:

   

1. Open the Routing.kt file and add the following route to the routing section:

   fun Application.configureRouting() { routing { staticResources("/content", "mycontent") // ... } }

   The meaning of this line is as follows:

   • Invoking staticResources() enables your application to provide standard website content, such as HTML and JavaScript files. Although this content can be executed within the browser, it is considered static from the server's point of view.

   • The URL /content specifies the path used to fetch this content.

   • The path mycontent is the name of the folder within which the static content will live. Ktor will look for this folder within the resources directory.

2. Add the following import if the IDE doesn’t add it automatically.

   import io.ktor.server.http.content.staticResources

3. In the Project tool window, right-click the src/main/resources folder and select New | Directory.

   Alternatively, select the src/main/resources folder, press ⌘Cmd+N (macOS) or Ctrl+N (Windows/Linux) and click Directory.

4. Name the new directory mycontent and press ↩Enter.

5. Right-click on the newly created folder and click New | File.

6. Name the new file sample.html and press ↩Enter.

7. Populate the newly created file page with valid HTML, for example:

   <html lang="en"> <head> <meta charset="UTF-8" /> <title>My sample</title> </head> <body> <h1>This page is built with:</h1> <ol> <li>Ktor</li> <li>Kotlin</li> <li>HTML</li> </ol> </body> </html>

8. Click on the rerun button () to restart the application.

9. When you open your browser at http://0.0.0.0:9292/content/sample.html the content of your sample page should be displayed:

   

1. Create a new subdirectory under src called test/kotlin.

2. Within src/test/kotlin create a new ApplicationTest.kt file.

3. Open the ApplicationTest.kt file and add the code below:

   class ApplicationTest { @Test fun testRoot() = testApplication { application { module() } val response = client.get("/") assertEquals(HttpStatusCode.OK, response.status) assertEquals("Hello World!", response.bodyAsText()) } }

   The testApplication() method creates a new instance of Ktor. This instance is running inside a test environment, as opposed to a server such as Netty.

   You can then use the application() method to invoke the same setup that is called from embeddedServer().

   Finally, you can use the built-in client object and JUnit assertions to send a sample request and check the response.

4. Add the following required imports:

   import io.ktor.client.request.get import io.ktor.client.statement.bodyAsText import io.ktor.http.HttpStatusCode import io.ktor.server.testing.testApplication import kotlin.test.Test import kotlin.test.assertEquals

Add a new dependency

In the Project tool window, navigate to the project root folder and follow the steps:

1. Open the gradle/libs.versions.toml file and add the following new library:

   [libraries] #... ktor-server-status-pages = { module = "io.ktor:ktor-server-status-pages", version.ref = "ktor" }

2. Open the build.gradle.kts file and add the new dependency as shown below:

   dependencies { // Added new dependency implementation(libs.ktor.server.status.pages) // Existing dependencies implementation(libs.ktor.server.core) implementation(libs.ktor.server.netty) implementation(libs.logback.classic) implementation(libs.ktor.server.config.yFaml) testImplementation(libs.ktor.server.test.host) testImplementation(libs.kotlin.test.junit) }

3. Reload the project by pressing Shift+⌘Cmd+I (macOS) or Ctrl+Shift+O (Windows/Linux).

Install the plugin and specify an exception handler

1. Navigate to the .configureRouting() method in Routing.kt and add the following lines of code:

   fun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { // ... } }

   These lines install the StatusPages plugin and specify what actions to take when an exception of type IllegalStateException is thrown.

2. Add the following import:

   import io.ktor.server.plugins.statuspages.StatusPages

Write sample code to trigger the handler

• Staying within the configureRouting() method, add the additional route as shown below:

  fun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { // ... get("/error-test") { throw IllegalStateException("Too Busy") } } }

  You have now added an endpoint with the URL /error-test. When this endpoint is triggered, an exception is thrown with the type used in the handler.

Restart and invoke the sample code

1. Click on the rerun button () to restart the application.

2. In your browser, navigate to the URL http://0.0.0.0:9292/error-test. You should see the error message displayed as shown below: