Build a full-stack web app with Kotlin Multiplatform

Run the embedded server

Instantiate a server with Ktor. You need to tell the embedded server that ships with Ktor to use the Netty engine on a port, in this case, 9090.

1. To define the entry point for the app, add the following code to src/jvmMain/kotlin/Server.kt:

   import io.ktor.http.* import io.ktor.serialization.kotlinx.json.* import io.ktor.server.engine.* import io.ktor.server.netty.* import io.ktor.server.application.* import io.ktor.server.plugins.compression.* import io.ktor.server.plugins.contentnegotiation.* import io.ktor.server.plugins.cors.routing.* import io.ktor.server.request.* import io.ktor.server.response.* import io.ktor.server.http.content.* import io.ktor.server.routing.* fun main() { embeddedServer(Netty, 9090) { routing { get("/hello") { call.respondText("Hello, API!") } } }.start(wait = true) }

   • The first API endpoint is an HTTP method, get, and the route under which it should be reachable, /hello.

   • All imports that are needed for the rest of the tutorial have already been added.

2. To start the application and see that everything works, execute the Gradle run task. You can use the ./gradlew run command in the terminal or run from the Gradle tool window:

   

3. Once the application has finished compiling and the server has started up, use a web browser to navigate to http://localhost:9090/hello to see the first route in action:

   

Later, like with the endpoint for GET requests to /hello, you'll be able to configure all of the endpoints for the API inside the routing block.

Install Ktor plugins

Before continuing with the application development, install the required plugins for the embedded servers. Ktor uses plugins to enable support for more features in the application like encoding, compression, logging, and authentication.

Add the following lines to the top of the embeddedServer block in src/jvmMain/kotlin/Server.kt:

Each call to install adds one feature to the Ktor application:

• ContentNegotiation provides automatic content conversion of requests based on their Content-Type and Accept headers. Together with the json() setting, this enables automatic serialization and deserialization to and from JSON, allowing you to delegate this task to the framework.

• CORS configures Cross-Origin Resource Sharing. CORS is needed to make calls from arbitrary JavaScript clients and helps prevent issues later.

• Compression greatly reduces the amount of data to be sent to the client by gzipping outgoing content when applicable.

Create a data model

Thanks to Kotlin Multiplatform, you can define the data model once as a common abstraction and refer to it from both the backend and frontend.

The data model for ShoppingListItem should have:

• A textual description of an item

• A numeric priority for an item

• An identifier

In src/commonMain/, create a kotlin/ShoppingListItem.kt file with the following content:

• The @Serializable annotation comes from the multiplatform kotlinx.serialization library, which allows you to define models directly in common code.

• Once you use this serializable ShoppingListItem class from the JVM and JS platforms, code for each platform will be generated. This code takes care of serialization and deserialization.

• The companion object stores additional information about the model − in this case, the path under which you will be able to access it in the API. By referring to this variable instead of defining routes and requests as strings, you can change the path to model operations. Any changes to the endpoint name only need to be made here - the client and server are adjusted automatically.

Add items to store

You can now use the ShoppingListItem model to instantiate some sample items and keep track of any additions or deletions made through the API.

Because there's currently no database, create a MutableList to temporarily store the ShoppingListItems. For that, add the following file-level declaration to src/jvmMain/kotlin/Server.kt:

The common classes are referred to as any other class in Kotlin – they are shared between all of the targets.

Create routes for the JSON API

Add the routes that support the creation, retrieval, and deletion of ShoppingListItems.

1. Inside src/jvmMain/kotlin/Server.kt, change your routing block to look as follows:

   routing { route(ShoppingListItem.path) { get { call.respond(shoppingList) } post { shoppingList += call.receive<ShoppingListItem>() call.respond(HttpStatusCode.OK) } delete("/{id}") { val id = call.parameters["id"]?.toInt() ?: error("Invalid delete request") shoppingList.removeIf { it.id == id } call.respond(HttpStatusCode.OK) } } }

   Routes are grouped based on a common path. You don't have to specify the route path as a String. Instead, the path from the ShoppingListItem model is used. The code behaves as follows:

   • A get request to the model's path (/shoppingList) responds with the whole shopping list.

   • A post request to the model's path (/shoppingList) adds an entry to the shopping list.

   • A delete request to the model's path and a provided id (shoppingList/47) removes an entry from the shopping list.

2. Check to ensure that everything is working as planned. Restart the application, head to http://localhost:9090/shoppingList, and validate that the data is properly served. You should see the example items in JSON formatting:

   

To test the post and delete requests, use an HTTP client that supports .http files. If you're using IntelliJ IDEA Ultimate Edition, you can do this right from the IDE.

1. In the project root, create a file called AddShoppingListElement.http and add a declaration of the HTTP POST request as follows:

   POST http://localhost:9090/shoppingList Content-Type: application/json { "desc": "Peppers 🌶", "priority": 5 }

2. With the server running, execute the request using the run button in the gutter.

   If everything goes well, the "run" tool window should show HTTP/1.1 200 OK, and you can visit http://localhost:9090/shoppingList again to validate that the entry has been added properly:

   

3. Repeat this process for a file called DeleteShoppingListElement.http, which contains the following:

   DELETE http://localhost:9090/shoppingList/AN_ID_GOES_HERE

   To try this request, replace AN_ID_GOES_HERE with an existing ID.

Now you have a backend that can support all of the necessary operations for a functional shopping list. Move on to building a JavaScript frontend for the application, which will allow users to easily inspect, add, and check off elements from their shopping list.

Serve the frontend

Unless explicitly configured otherwise, a Kotlin Multiplatform project just means that you can build the application for each platform, in this case JVM and JavaScript. However, for the application to function properly, you need to have both the backend and the frontend compiled. In fact, you want the backend to also serve all of the assets belonging to the frontend – an HTML page and the corresponding .js file.

In the template project, the adjustments to the Gradle file have already been made. Whenever you run the server with the run Gradle task, the frontend is also built and included in the resulting artifacts. To learn more about how this works, see the Relevant Gradle configuration section.

The template already comes with a boilerplate index.html file in the src/commonMain/resources folder. It has a root node for rendering components and a script tag that includes the application:

This file is placed in the common resources instead of a jvm source set to make tasks for running the JS application in the browser (jsBrowserDevelopmentRun and jsBrowserProductionRun) accessible to the file as well. It's helpful if you need to run only the browser application without the backend.

While you don't need to make sure that the file is properly available on the server, you still need to instruct Ktor to provide the .html and .js files to the browser when requested.

Serve HTML and JavaScript files from Ktor

For simplicity, the index.html file will be served on the root route / and expose the JavaScript artifact in the root directory.

1. In src/jvmMain/kotlin/Server.kt, add the corresponding routes to the routing block:

   get("/") { call.respondText( this::class.java.classLoader.getResource("index.html")!!.readText(), ContentType.Text.Html ) } staticResources("/", "static") route(ShoppingListItem.path) { // ... }

2. To confirm that everything went as planned, run the application again with the Gradle run task.

3. Navigate to http://localhost:9090/. You should see a page saying "Hello, Kotlin/JS":

   

Edit configuration

While you are developing, the build system generates development artifacts. This means that no optimizations are applied when the Kotlin code is turned into JavaScript. That makes compile times faster but also results in larger JS files. When you deploy your application to the web, this is something you want to avoid.

To instruct Gradle to generate optimized production assets, set the necessary environment variable. If you are running your application on a deployment system, you can configure it to set this environment variable during the build. If you want to try out production mode locally, you can do it in the terminal or by adding the variable to the run configuration:

1. In IntelliJ IDEA, select the Edit Configurations action:

   

2. In the Run/Debug Configurations menu, set the environment variable:

   ORG_GRADLE_PROJECT_isProduction=true

   

Subsequent builds with this run configuration will perform all available optimizations for the frontend part of the application, including eliminating dead code. They will still be slower than development builds, so it would be good to remove this flag again while you are developing.

Write the API client

To display data, you need to obtain it from the server. For this, build a small API client.

This API client will use the ktor-clients library to send requests to HTTP endpoints. Ktor clients use Kotlin's coroutines to provide non-blocking networking and support plugins like the Ktor server.

In this configuration, the JsonFeature uses kotlinx.serialization to provide a way to create typesafe HTTP requests. It takes care of automatically converting between Kotlin objects and their JSON representation and vice versa.

By leveraging these properties, you can create an API wrapper as a set of suspending functions that either accept or return ShoppingItems. Create a file called Api.kt and implement them in src/jsMain/kotlin:

Build the user interface

You've laid the groundwork on the client and have a clean API to access the data provided by the server. Now you can work on displaying the shopping list on the screen in a React application.

Set up MongoDB

Install MongoDB Community Edition on your local machine from the official MongoDB website. Alternatively, you can use a containerization tool like podman to run a containerized instance of MongoDB.

After installation, ensure that you are running the mongodb-community service for the rest of the tutorial. You'll use it to store and retrieve list entries.

Include KMongo in the process

KMongo is a community-created Kotlin framework that makes it easy to work with MongoDB from Kotlin/JVM code. It also works nicely with kotlinx.serialization, which is used to facilitate communication between client and server.

By making the code use an external database, you no longer need to keep a collection of shoppingListItems on the server. Instead, set up a database client and obtain a database and a collection from it.

1. Inside src/jvmMain/kotlin/Server.kt, remove the declaration for shoppingList and add the following three top-level variables:

   val client = KMongo.createClient().coroutine val database = client.getDatabase("shoppingList") val collection = database.getCollection<ShoppingListItem>()

2. In src/jvmMain/kotlin/Server.kt, replace definitions for the GET, POST, and DELETE routes to a ShoppingListItem to make use of the available collection operations:

   get { call.respond(collection.find().toList()) } post { collection.insertOne(call.receive<ShoppingListItem>()) call.respond(HttpStatusCode.OK) } delete("/{id}") { val id = call.parameters["id"]?.toInt() ?: error("Invalid delete request") collection.deleteOne(ShoppingListItem::id eq id) call.respond(HttpStatusCode.OK) }

   In the DELETE request, KMongo's type-safe queries are used to obtain and remove the correct ShoppingListItem from the database.

3. Start the server using the run task, and navigate to http://localhost:9090/. On the first start, you'll be greeted by an empty shopping list as is expected when querying an empty database.

4. Add some items to your shopping list. The server will save them to the database.

5. To check this, restart the server and reload the page.

Inspect MongoDB

To see what kind of information is actually saved in the database, you can inspect the database using external tools.

If you have IntelliJ IDEA Ultimate Edition or DataGrip, you can inspect the database contents with these tools. Alternatively, you can use the mongosh command-line client.

1. To connect to the local MongoDB instance, in IntelliJ IDEA Ultimate or DataGrip, go to the Database tab and select + | Data Source | MongoDB:

   

2. If it's your first time connecting to a MongoDB database this way, you might be prompted to download missing drivers:

   

3. When working with a local MongoDB installation that uses the default settings, no adjustments to the configuration are necessary. You can test the connection with the Test Connection button, which should output the MongoDB version and some additional information.

4. Click OK. Now you can use the Database window to navigate to your collection and look at everything stored in it:

   

Specify the PORT variable

On managed platforms, the port on which the application should run is often determined externally and exposed through the PORT environment variable. If present, you can respect this setting by configuring embeddedServer in src/jvmMain/kotlin/Server.kt:

Ktor also supports configuration files that can respect environment variables. To learn more about how to use them, check out the official documentation.

Specify the MONGODB_URI variable

Managed platforms often expose connection strings through environment variables – for MongoDB, this might be the MONGODB_URI string, which needs to be used by the client to connect to the database. Depending on the specific MongoDB instance you're trying to connect to, you might need to append the retryWrites=false parameter to the connection string.

To properly satisfy these requirements, instantiate the client and database variables in src/jvmMain/kotlin/Server.kt:

This ensures that the client is created based on this information whenever the environment variables are set. Otherwise (for instance, on localhost), the database connection is instantiated as before.

Create the Procfile

Managed cloud platforms like Heroku or PaaS implementations like Dokku also handle the lifecycle of your application. To do so, they require an "entry point" definition. These two platforms use a file called Procfile that you have in the project root directory. It points to the output generated by the stage task (which is included in the Gradle template already):

Turn on production mode

To turn on a compilation with optimizations for the JavaScript assets, pass another flag to the build process. In the Run/Debug Configurations menu, set the environment variable ORG_GRADLE_PROJECT_isProduction to true. You can set this environment variable when you deploy the application to the target environment.