Migration from 8.x to 9.x

KVision 9.0.0 is a major upgrade with changes affecting both functionalities and application structure. The goal of this release is to simplify the maintenance of the framework and allow me to continue supporting it. This required sacrificing several modules that, to my knowledge, were not widely (or even at all) used. At the same time, the KVision architecture was modernized, allowing for fixing issues and adding support for new features.

This is the list of incompatibilities you may encounter when migrating your application to KVision 9.0.0.

General changes

• The kvision-electron , kvision-cordova and kvision-onsenui modules were removed. If you use any of these modules, migration to KVision 9.x is not possible. Please let me know if this is your case.

• All code has been migrated to ES modules and es2015 target. As a result the require function, used for importing resources and integrating NPM libraries, is no longer available. Use @JsModule annotation instead. For instance, if you use this code to import CSS and JSON files:

class App : Application() {
    init {
        require("css/kvapp.css")
    }
    override fun start() {
        I18n.manager =
                DefaultI18nManager(
                    mapOf(
                        "en" to require("i18n/messages-en.json"),
                        "pl" to require("i18n/messages-pl.json"),
                    )
                )
        // ...
    }
}

you should now use this:

import io.kvision.utils.useModule

@JsModule("/kotlin/modules/css/kvapp.css")
external val kvappCss: dynamic

@JsModule("/kotlin/modules/i18n/messages-en.json")
external val messagesEn: dynamic

@JsModule("/kotlin/modules/i18n/messages-pl.json")
external val messagesPl: dynamic

class App : Application() {
    init {
        useModule(kvappCss)
    }
    override fun start() {
        I18n.manager =
                DefaultI18nManager(
                    mapOf(
                        "en" to messagesEn,
                        "pl" to messagesPl,
                    )
                )
        // ...
    }
}

You need to move the resources processed by webpack (e.g. css files, images, po files or hbs templates) to the src/jsMain/resources/modules directory and use /kotlin/modules prefix, when importing them.

• Replace src/jsMain/resources/i18n/messages.pot with src/jsMain/resources/modules/i18n/messages.pot in the .gettext.json file, if you have it in your project.

• Change module.hot to js("import.meta.webpackHot").unsafeCast<Hot?>() when using HMR.

• Move the content of the src/jsMain/web directory to src/jsMain/resources . The web directory is no longer used.

• Add useEsModules() and compilerOptions { target.set("es2015") } to your build.gradle.kts file. Check Creating new application chapter for reference.

• Add kotlin.js.ir.output.granularity=per-file property to your gradle.properties file.

• When using kvision-pace module with the default theme, you need to provide a parameter to Pace.init() call. Use the code like this:

@JsModule("pace-progressbar/themes/blue/pace-theme-flash.css")
external val paceThemeFlash: dynamic

class App : Application() {
    init {
        Pace.init(paceThemeFlash)
    }
}

• Remove these two lines from webpack.config.d/webpack.js file:

config.resolve.modules.push("../../processedResources/js/main");
config.resolve.conditionNames = ['import', 'require', 'default'];

Fullstack changes

All kvision-server-* modules were removed and KVision by itself no longer provides fullstack interfaces. You have to migrate your application to use Kilua RPC library. This library was created as a standalone project that modernizes concepts originally implemented in KVision.

KVision still provides kvision-common-remote module, which supports date and time types declared in io.kvision.types package, so you don't have to change your application logic.

Note: Kilua RPC temporarily doesn't support Micronaut server, because of dependencies conflicts and no KSP2 support.

To migrate your application:

• Add versions of KSP and Kilua RPC to your gradle.properties file:

systemProp.kspVersion=2.1.20-2.0.0
systemProp.kiluaRpcVersion=0.0.32

• Add two Gradle plugins to your project:

plugins {
    val kotlinVersion: String by System.getProperties()
    kotlin("plugin.serialization") version kotlinVersion
    kotlin("multiplatform") version kotlinVersion
    val kspVersion: String by System.getProperties()      // new
    id("com.google.devtools.ksp") version kspVersion      // new
    val kiluaRpcVersion: String by System.getProperties() // new
    id("dev.kilua.rpc") version kiluaRpcVersion           // new
    val kvisionVersion: String by System.getProperties()
    id("io.kvision") version kvisionVersion
}

• Remove kvision-server-* dependency from your common source set and add new dependencies on Kilua RPC (use implementation() instead of api() ):

val commonMain by getting {
    dependencies {
        implementation("dev.kilua:kilua-rpc-ktor-koin:$kiluaRpcVersion")
        implementation("io.kvision:kvision-common-remote:$kvisionVersion")
    }
}

• Kilua RPC doesn't support Guice, so if you are using it in your app, you should migrate to Koin or use manual bindings without any dependency injection, like this:

initRpc {
    registerService<IEncodingService> { EncodingService() }
}

• Replace annotations in your common code:

  • io.kvision.annotations.KVService to dev.kilua.rpc.annotations.RpcService

  • io.kvision.annotations.KVBinding to dev.kilua.rpc.annotations.RpcBinding

  • io.kvision.annotations.KVBindingMethod to dev.kilua.rpc.annotations.RpcBindingMethod

  • io.kvision.annotations.KVBindingRoute to dev.kilua.rpc.annotations.RpcBindingRoute

  • io.kvision.annotations.KVServiceException to dev.kilua.rpc.annotations.RpcServiceException

• Replace types:

  • io.kvision.types.Decimal to dev.kilua.rpc.types.Decimal

  • io.kvision.remote.RemoteOption todev.kilua.rpc.RemoteOption

  • io.kvision.remote.SimpleRemoteOption todev.kilua.rpc.SimpleRemoteOption

  • io.kvision.remote.RemoteData todev.kilua.rpc.RemoteData

  • io.kvision.remote.RemoteFilter todev.kilua.rpc.RemoteFilter

  • io.kvision.remote.RemoteSorter todev.kilua.rpc.RemoteSorter

  • io.kvision.remote.RemoteSerialization todev.kilua.rpc.RpcSerialization

  • io.kvision.remote.ServiceException todev.kilua.rpc.ServiceException

  • io.kvision.remote.SecurityException todev.kilua.rpc.SecurityException

  • io.kvision.remote.ContentTypeException todev.kilua.rpc.ContentTypeException

  • io.kvision.remote.KVServiceManager todev.kilua.rpc.RpcServiceManager

• Your service class in JVM sources set should no longer be actual . Remove actual keyword and @Suppress("ACTUAL_WITHOUT_EXPECT") annotation if you use it.

• Replace functions:

  • io.kvision.remote.getServiceManager todev.kilua.rpc.getServiceManager

  • io.kvision.remote.getAllServiceManagers todev.kilua.rpc.getAllServiceManagers

  • io.kvision.remote.serviceMatchers todev.kilua.rpc.serviceMatchers

  • io.kvision.remote.getService todev.kilua.rpc.getService

• Replace kv_remote_url_prefix configuration option with rpc_url_prefix .

• Add registerRemoteTypes() call to your main() functions in both js and jvm sources set.

• The production version of the application is now assembled with jarWithJs Gradle task.

Spring Boot

• You need to modify the structure of your Spring Boot project, because Kotlin 2.1.20 no longer supports using Kotlin Multiplatform and Spring Boot Gradle plugin in the same module. You need to add additional application submodule. Please check addressbook-fullstack-spring-boot example application for reference.

• Using io.spring.dependency-management Gradle plugin can cause problems with dependencies (see KT-75643). Use Spring BOM instead.