In this post, we'll be going over how to create a basic Ktor project and configuring it with autoreload, a feature that automatically rebuilds the code on file changes. Furthermore, we'll explore two ways of building and running the application: via the command line and via the IDE.
Creating a Ktor project
Using the latest version of IntelliJ IDEA, ensure the latest Ktor plugin is installed.
This plugin provides us with a convenient user interface to generate new Ktor projects.
Summon the New Project window by selecting the File > New > New Project... menu.
To get quickly started, click Next to start from a minimal Ktor project. Fill out the project's Maven GroupId and ArtifactId:
Continue to the next step to name the Gradle project:
In this example, the name is "MyFirstBasicKtorProject". Remember this name to set up Ktor's autoreload feature as this directory will be part of the Java classpath. After selecting Finish, open the
As seen in this file, the main function is starting the Netty server engine. This engine references the
application.conf HOCON configuration file under the resources directory:
This file defines the port that Ktor will use. This port can also be supplied via the
PORT environment variable (in which case it will override the
8080 port defined above). Additionally, a module is predefined within the
Application.kt file. Separate modules can be used to separate the definition of features.
Defining a GET HTTP controller
For starters, let's define a basic GET controller that responds with plain text:
Application class provides a
routing block to define HTTP controllers. In this example, we are defining a root path GET controller. The
get block provides a reference to the
PipelineContext, which helps provide
call, an object used to read the request and send a response. This instance utilizes the
respondText function to respond with plain text. Although now we're ready to run the application with the
run gradle task, let's first configure autoreload.
Autoreload is a Ktor configuration feature that enables automatically rebuilding the project on file saves so that we don't have to manually rebuild after changes. To enable this, we first must add the current classpath (correlates to the project's directory name, e.g.
MyFirstBasicKtorProject) to the
ktor.deployment.watch HOCON configuration:
Building and running via the command line
If you prefer running the project via the command line, you can first run
./gradlew build -t in a terminal window. The
-t flag defines a continuous build: as file changes happen, the build is re-triggered. Because the command is continuous, we will need a separate terminal window to run the next command:
./gradlew run. This will run the application.
Building and running via IntelliJ IDEA
From the top-right of the IDE, select Add Configuration...
From the Run/Debug Configurations window, click the + button and select the Gradle option. Name the configuration (in this example, it is "Continuous Build"). Next, select the project from the folder icon drop down. For the Tasks option, type
build. Additionally, supply the
-t argument in order to configure this Gradle task as continuous. Click Apply to save the configuration.
Next, we'll create a run configuration by repeating the same steps to create a new configuration (via clicking the + button). Additionally, we will define the Continuous Build configuration as a dependency for the run configuration. To do so, click the + button under the Before launch section and select Run Another Configuration. Select Continuous Build from the drop down menu and select OK to complete setting up the configurations.
Play the Run configuration:
Because the Continuous Build is never-ending, the actual Run configuration does not run initially. To mitigate this, click on the Rerun icon.
We should now have both configurations running:
Viewing the running app in the browser
In a browser, load
http://localhost:8080/ to view the plain text we defined:
If we go back to the
Application.kt file, make a change, and save the file...
...then we will be able to refresh the browser and view the change without needing to manually rebuild the application!
To conclude, in this post we learned how to create a new Ktor project in IntelliJ IDEA. We learned how to:
- Define a basic HTTP GET controller
- Configure the Ktor project for autoreload
- Continuously build and run a Ktor project from the command line
- Continuously build and run a Ktor project using the IDE
Thank you for your time! To learn more about Ktor, please refer to the Ktor documentation.