Ktor 3.0.0 Help

Creating a new Ktor project

Ktor is an asynchronous framework for creating microservices, web applications, and more. You can create and configure a new Ktor project using a dedicated plugin for IntelliJ IDEA Ultimate, or using a web-based project generator. In this guide, we'll show you how to create, run, and test a simple Ktor application.

Prerequisites

Before starting this tutorial:

Create a new Ktor project

This section describes project setup using the Ktor plugin for Intellij IDEA Ultimate. If you are using IntelliJ IDEA Community Edition, use the Ktor Project Generator instead.

To create a new Ktor project, open IntelliJ IDEA, and follow the steps below:

  1. On the Welcome screen, click New Project.

    Otherwise, from the main menu, select File | New | Project.

  2. In the New Project wizard, choose Ktor from the list on the left.

  3. On the right pane, you can specify the following settings:

    Ktor Project Settings

    • Name: Specify a project name.

    • Location: Specify a directory for your project.

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

    • Website: Specify a domain used to generate a package name.

    • Artifact: This field shows a generated artifact name.

    • Ktor version: Choose the required Ktor version.

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

    • Configuration in: Choose Code to specify server parameters in code.

    • Add sample code: Leave this option enabled to add sample code for plugins added on the next page.

    In this tutorial, we leave the default values for these settings. Click Next to go to the next page.

  4. On the next page, you can choose a set of plugins - building blocks that provide common functionality of a Ktor application, for example, authentication, serialization and content encoding, compression, cookie support, and so on.

    Ktor plugins

    For now, let's install only the Routing plugin to handle incoming requests. Start typing routing in the top left search box, find Routing in the list, and click Add.

    Add the Routing plugin

    Click Create and wait until IntelliJ IDEA generates a project and installs the dependencies.

Now we are ready to run the created application.

Run a Ktor application

To run the created Ktor application, follow the steps below:

  1. Invoke the Project view and open the Application.kt file placed by the following path:

    src/main/kotlin/com/example/Application.kt

    Project view

  2. The Application.kt file has the following code added automatically:

    package com.example import io.ktor.server.application.* import io.ktor.server.engine.* import io.ktor.server.netty.* import com.example.plugins.* fun main() { embeddedServer(Netty, port = 8080, host = "0.0.0.0", module = Application::module) .start(wait = true) } fun Application.module() { configureRouting() }

    The main parts of this code are:

    • The embeddedServer function is used to configure server parameters in code and run an application.

    • configureRouting is an extension function that defines routing. This function is declared in a separate plugins package (the Routing.kt file).

      package com.example.plugins import io.ktor.server.routing.* import io.ktor.http.* import io.ktor.server.application.* import io.ktor.server.response.* import io.ktor.server.request.* fun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } } }

      The get function within the routing block receives GET requests made to the / path and responds with a plain text response.

  3. To run the application, click the gutter icon next to the main function and choose Run 'ApplicationKt'.

    Run a Ktor application

  4. Wait until Intellij IDEA runs the application. The Run tool window should show the following message:

    [main] INFO ktor.application - Responding at http://0.0.0.0:8080
    Run tool window

    This means that the server is ready to accept requests at the http://0.0.0.0:8080 address. You can click this link to open the application in a default browser:

    Ktor app in a browser

Test a Ktor application

Now let's test the created application:

  1. Open the ApplicationTest.kt file placed by the following path: src/test/kotlin/com/example/ApplicationTest.kt. In this file, the testApplication function is used to make the GET request to / and check a response status and content.

  2. To run a test, click the gutter icon next to the testRoot function and choose Run 'ApplicationTest.test'.

    Run a test

  3. Wait until IntelliJ IDEA performs a test and displays results in the Run tool window.

    Run test output

Next steps

Create real-world Ktor applications with the help of tutorials:

Last modified: 12 December 2022
Welcome Creating HTTP APIs