Forem: Touchlab

Kotlin 1.9.20: Streamlining Source Sets in Multiplatform Project

Jigar Brahmbhatt — Tue, 26 Mar 2024 13:57:17 +0000

The release of Kotlin 1.9.20 marked a significant milestone for Kotlin Multiplatform enthusiasts, as this update moved Kotlin Multiplatform to Stable. Kotlin 1.9.20 introduces several notable features and enhancements. Among these updates, the new source set hierarchy template by the Kotlin Gradle Plugin stands out to me for its ability to simplify configuration complexities. It was launched as experimental in Kotlin 1.8.20 and has been made default in Kotlin 1.9.20.

Simplified iOS Target Configuration

In the common Kotlin Multiplatform project set-up, you would have seen specific source set setup for two or three iOS targets like for X64, Arm64.

Instead of the common and confusing 'ios()' target, one must always declare specific targets like 'iosArm64()' as required. Once one of the iOS targets is declared, the default template would automatically create iosMain source set. So no more val iosMain by creating boilerplate required.

Before 1.9.20

After 1.9.20

kotlin {
    ios()
    iosSimulatorArm64()

    sourceSets {
        val commonMain by getting

        val iosMain by creating {
            dependsOn(commonMain)
        }

        val iosX64Main by getting {
            dependsOn(iosMain)
        }

        val iosArm64Main by getting {
            dependsOn(iosMain)
        }

        val iosSimulatorArm64Main by getting {
            dependsOn(iosMain)
        }
    }
}

kotlin {
    iosX64()
    iosArm64()
    iosSimulatorArm64()

    // The iosMain source set is now created automatically
    // You can directly use the reference now
    iosMain.dependencies {
        implementation("...")
    }
}

If you've an old KMP project and still have reference of darwinMain, you can simply rename it to appleMain now as that encapsulates all other apple targets.

Checkout the full hierarchy template!

Streamlined Custom Source Sets

Managing custom source sets in Kotlin Multiplatform projects is now more straightforward with Kotlin 1.9.20. The update simplifies the process of setting up dependencies between source sets, reducing the need for extensive boilerplate code and enhancing overall readability.

For example, let's assume that you already have kotlin/JS support with jsMain/jsTest source sets. Now, you want to add kotlinWasm support. Since wasmJs and kotlinJs can share a common source, you want to introduce a new jsAndWasmJsMain parent source set for common code sharing between them. Instead of using by creating, you can declare new custom source set inside applyDefaultHierarchyTemplate {}.

Before 1.9.20

After 1.9.20

kotlin {
    js()
    wasmJs()

    sourceSets {
        val commonMain by getting
        val commonTest by getting

        val jsAndWasmJsMain by creating {
            dependsOn(commonMain)
            getByName("jsMain").dependsOn(this)
            getByName("wasmMain").dependsOn(this)
        }

        val jsAndWasmJsTest by creating {
            dependsOn(commonTest)
            getByName("jsTest").dependsOn(this)
            getByName("wasmTest").dependsOn(this)
        }
    }
}

kotlin {
    js()
    wasmJs()

    // This is an experimental API, so opt-in is required
    @OptIn(ExperimentalKotlinGradlePluginApi::class)
    applyDefaultHierarchyTemplate {
        // create a new group that
        // depends on `common`
        common {
            // Define group name without
            // `Main` as suffix
            group("jsAndWasmJs") {
                // Provide which targets would
                // be part of this group
                withJs()
                withWasm()
            }
        }
    }

    // Now you will already have `jsAndWasmJsMain`
}

Manually apply the template

Note that if you have explict by creating usage for custom source set then defauly template hierarchy would not apply automatically and you would see warning about the same.

w: The Default Kotlin Hierarchy Template was not applied to 'project ':XXX'':
Explicit .dependsOn() edges were configured for the following source sets:
[XXX]

In order to get the default hierachy, you would have to call applyDefaultHierarchyTemplate() manually once you declare all the targets.

Also, checkout Opting Out of Default Templates

Enhanced Code Completion Support

The updated source set hierarchy template enhances code completion support in the IDE. Developers can now utilize predefined source sets directly, eliminating the need for repetitive declarations and enhancing overall development efficiency.

So even in simple cases, you can still clean up your source set declarations, and make them more readable.

Default before 1.9.20

With 1.9.20

kotlin {
    // ...
    sourceSets {
        val commonMain by getting {
            dependencies {
                // ...
            }
        }
        val androidMain by getting {
            dependencies {
                // ...
            }
        }
        val iosMain by creating {
            dependencies {
                // ...
            }
        }
    }
}

kotlin {
    // ...
    sourceSets {
        commonMain.dependencies {
            // ...
        }
        androidMain.dependencies {
            // ..
        }
        iosMain.dependencies {
            // ...
        }
    }
}

Android instrumented test changes

With introduction of the new Android source set layout (now default starting Kotlin 1.9.0), the androidInstrumentedTest source set doesn't automatically depend on commonTest.

In order to have that dependency set-up, with 1.9.0, you would need to explicitly set the dependsOn relationship between them, and with 1.9.20, you now just need to set the correct sourceSetTree property inside android target.

With 1.9.0

With 1.9.20

kotlin {
    // ...
    sourceSets {
        val commonTest by getting
        val androidInstrumentedTest by getting {
            dependsOn(commonTest)
        }
    }
}

kotlin {
    androidTarget {
        // This is an experimental API, so opt-in is required
        @OptIn(ExperimentalKotlinGradlePluginApi::class)
        instrumentedTestVariant {
            // This makes instrumented tests depend on commonTest source
            sourceSetTree.set(KotlinSourceSetTree.test)
        }
    }
}

Opting Out of Default Templates

For projects with existing complex source set hierarchies, Kotlin 1.9.20 offers the flexibility to opt-out of the default template. By setting kotlin.mpp.applyDefaultHierarchyTemplate=false in the gradle.properties, developers can retain their current configurations.

Conclusion

As you transition to Kotlin 1.9.20, consider how these improvements can optimize your Gradle configurations and enhance your multiplatform development workflow.

We recently updated most of our OSS projects to use Kotlin 1.9.22, leveraging the benefits of these enhancements. We hope you find the transition as beneficial as we have.

Share your experiences and questions with us on #touchlab-tools channel on Kotlin Slack. Also, you can reach out to me at @shaktiman_droid on Twitter(X) or LinkedIn. Happy coding!

Amper: a new way to configure Gradle projects?

Gustavo Fão Valvassori — Fri, 08 Dec 2023 12:05:34 +0000

Earlier this month, Kotlin Multiplatform went stable. And just a couple of weeks later, they announced a new tool to help with one of the biggest issues we have, configuration. Currently, KMP projects use Gradle as a Build System, and we must agree that it's a great tool. But the complexity around it for new users is a big issue.

Amper is a tool to help you configure your projects using a markup language. The main goal is to replace the Groovy/Kotlin programming language with something that can enforce a declarative approach. With a declarative paradigm, you can only declare what needs to be done without implementing it. If you already have experience with Maven, it may be familiar to you.

Please note that the tool is in the early stages of development, and its goal is to validate the idea before putting more effort into it. With that in mind, be aware that syntax, language, and other things may change in the future, and it’s a very experimental tool.

How does it work?

According to the docs, Amper is implemented as a Gradle plugin and uses YAML for its project configuration format. In other words, it's still a Gradle environment, but it will use an additional YAML file to configure the project. To be able to use it, you need one of the following environments:

Use one of the following IDEs:
1. IntelliJ IDEA 2023.3 or newer and the Amper Plugin; or
2. Fleet 1.26 or newer;
Use the Amper build plugin to enable it:
1. In your settings.gradle.kts, add this plugin: id("org.jetbrains.amper.settings.plugin").version("0.1.1")

When you open a project with the Amper Plugin in the IDE, it will look for the module.yaml file. This file will contain the configuration for the module (library or application), dependencies, and other project configurations (like the Java version).

Also worth noting that it also changes the project architecture. Instead of having a directory for your source set artifacts, you will have multiple src directories. In other words, your commonMain/src/kotlin will be only src now, and your iosMain/src/kotlin will be only src@ios. This is a bit confusing at first, but it helps flatten the project structure.

Our Thoughts

Amper comes to fix a huge problem for all KMP developers. We at Touchlab look forward to anything that will reduce the configuration complexity in KMP, and Amper is hopefully a step in the right direction. The Gradle team seems to be on board, at least with the concept. Hopefully the combined efforts will result in something that is truly easier to use and more maintainable.

The integration with the IDEs works fine for configuration. It knows the configuration schema and gives you valid suggestions for properties. Unfortunately, the configuration of the third-party plugins is not currently supported, but it's on their roadmap.

The project APIs are small and only supports a short range of configurations. For basic contexts it works like a charm, but when you need to do something more complex, you may need to work with Gradle again.

The Gradle interop is great. You can still have a build.gradle.kts file to make custom configurations that are not available yet in the YAML file. One does not replace the other, but complement instead. This will be useful if you need to create intermediate source-sets, configure plugins or even import libraries that have a different configuration.

For now, we recommend testing it it out on smaller projects that may not have a big impact with future changes, as it's still experimental. But we are excited to see how it will evolve in the future. If you are using it, don't forget to share your opinions with the Jetbrains team on their Feedback Form and their Slack Channel.

Additional Resources

Getting Started with Compose for Web

Gustavo Fão Valvassori — Fri, 01 Dec 2023 21:34:32 +0000

If you are a Kotlin developer like me, you are probably very excited about Jetpack Compose. It’s a modern UI toolkit for developing apps, and with the great work from JetBrains, it’s becoming a really interesting solution.

As a mobile developer, I’ve never gone in the weeds on how to properly develop sites with HTML, CSS, and JS. My closest experience was with React Native back in 2018. But now, with Compose, using a Kotlin DSL, I feel comfortable on doing this.

Compose Runtime and Component Library

Before creating a project and start coding, it's important to have a small introduction to Compose runtimes. As of now, Compose has two different runtimes on the web:

JS + HTML
Wasm + Canvas

They both use the Compose Runtime underneath, but they use different components. Long story short:

The HTML version will have HTML composable components (like H1, P, Span, Input, Div, etc.)
The Canvas version will have similar components as the Android version as it uses SKIA to draw on the Canvas.

Both of them are experimental. Note that choosing how you want to build your application will impact on possible code-sharing with native if this is what you want.

For this series of posts, I'll use the HTML version and I will be able to explore more the web components.

Creating the project

Now that we know what runtime/components we want to use, we need to create a project. My first idea was to use the KMP project wizard, but unfortunately, the Web target is not available as an option for now. As a workaround, I had to create a new clean project using IntelliJ IDEA and add the dependencies manually.

Using a clean template you will reduce the amount of code that needs to be removed/updated to make the project work. But if you prefer to use any other IDE/Template, feel free to do so and share your experience with us later :)

With that, the configuration is completed with a few extra lines:

Change the Kotlin plugin from JVM to MULTIPLATFORM
Add the Compose plugin
Declare JS source-sets
Import the dependencies
Create an HTML file



plugins {
    kotlin("multiplatform") version "1.9.20" // Make this multiplatform
    id("org.jetbrains.compose") version "1.5.10" // Add compose plugin
}

kotlin {
    js(IR) { // Declare JS source-sets
        browser()
        binaries.executable()
    }
    sourceSets {
        val jsMain by getting {
            dependencies {
                                // Import libraries
                implementation(compose.html.core)
                implementation(compose.runtime)
            }
        }
        val jsTest by getting {
            dependencies {
                implementation(kotlin("test-js"))
            }
        }
    }
}

If you have a trained eye for Gradle configuration, you probably already noticed that we are importing the Compose HTML library. And that's why we need to create an HTML page that will load and be filled by our Composable code. This file should be located at jsMain/resources/index.html.



<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Compose Web</title>
    </head>
    <body>
        <div id="root"></div>
        <script src="compose-sweeper.js"></script>
    </body>
</html>

This can be very simple, just load the JS built from your Kotlin code and create a DOM element that will be you compose root.

Running the project

As with any other project using Gradle as the build system, you will run most of your changes with the gradlew binary (or the gradlew.bat if you are running on Windows). Even though there are multiple commands listed when you call gradlew tasks, the important ones are three:

./gradlew jsBrowserDevelopmentRun - Start development server;
1. This call supports the --continuous build flag that can be used for reloading the app when the code changes;
./gradlew jsBrowserProductionWebpack - Generate the bundle version of your project.
1. It will spit out a static site at the build/dist/js/productionExecutable dir;
./gradlew allTests - Run all unit tests you have implemented for your project;

How does this work?

When you start the development server, it will compile your Kotlin code and run the main() function. On this function, you can call the renderComposable method to start a composable block inside a window element.



fun main() {
    renderComposable(rootElementId = "root") {
        Text("Hello World")
    }
}

As you can see, it will render all the content inside one root element we've defined on previous sections.

Lastly, as you can see at the end of the body block, we are importing the JS file created while building our application. The default name is just the project name with a .js extension.

Now that we have everything in place, we can finally run our server and have the following result:

Final Thoughts

In this first article, we are just exploring how to create and set up your project. But we can already say that Compose Web is a promising alternative for Kotlin developers who don’t want to learn HTML/CSS/JS (even though you will need it).

In future posts, we will dig into more topics, like how to use HTML Components, Styling with CSS, Handling, and Listening to DOM events. After all the articles, you will be able to fully understand how I’ve built this Minesweeper game only using Compose.

Kermit Now Supports WASM

Jigar Brahmbhatt — Mon, 30 Oct 2023 19:09:32 +0000

What is Kotlin/Wasm?

For Kotlin Multiplatform developers, the conversation has shifted to WebAssembly — a notable addition to the Kotlin Multiplatform (KMP) ecosystem. WebAssembly, often abbreviated as WASM, is a binary instruction format tailored for web browsers. Its main goal is to execute high-performance code at speeds close to native applications. WebAssembly enjoys broad support across modern browsers, boasting approximately 96% coverage according to caniuse.

While it's not meant to be directly written, there's a fascinating aspect called WebAssembly Text Format (.wat). This format allows developers to represent code in a readable text format. For those curious minds, delve deeper into this format by reading Mozilla's guide.

While WebAssembly isn't a newcomer, ongoing developments, such as the anticipated WebAssembly Garbage Collection (WASM GC), make it an evolving technology. Kotlin, recognizing the potential of WebAssembly, has embraced it with the Kotlin/WASM compiler. The Kotlin team is actively ensuring they stay ahead of the curve with the Kotlin/WASM compiler, already incorporating support for features like WASM GC. What makes Kotlin/WASM noteworthy is its ability to allow developers to write code in their preferred language and seamlessly compile it into a WebAssembly binary.

Kermit Steps into the Wasm Arena

Given Kermit's popularity in the Kotlin Multiplatform (KMP) realm, the community asked for Wasm support. It was exciting to gain firsthand experience with WASM for integration into Kermit.

Step #1 - Adding the Wasm Target

The initial step seemed straightforward: add the wasm target in our build scripts. However, reality hit when we discovered that some of Kermit's dependencies lacked support for Wasm. This underscored a critical lesson for library developers: ensure upstream libraries are compatible with all KMP targets your project aims to include.

import org.jetbrains.kotlin.gradle.targets.js.dsl.ExperimentalWasmDsl

kotlin {
    ...
    @OptIn(ExperimentalWasmDsl::class)
    wasm {
        browser()
        binaries.executable()
    }
}

You can also add nodejs and d8 environment support inside the wasm target, but exploration around that is out of scope for this post.

Step #2 - Common Source Set

Understanding the possibility for interoperability between Kotlin/JS and Kotlin/Wasm, we defined a common source set shared between js and wasm. This approach ensures code reusability between the two targets.

kotlin {
    sourceSets {
        val jsAndWasmMain by creating {
            dependsOn(commonMain)
            jsMain.dependsOn(this)
            wasmMain.dependsOn(this)
        }
        val jsAndWasmTest by creating {
            dependsOn(commonTest)
            jsTest.dependsOn(this)
            wasmTest.dependsOn(this)
        }
    }
}

Step #3 - Code Migration

Migrating code from jsMain to jsAndWasmMain wasn't a simple copy-paste endeavor. Here, we encountered two challenges:

Problem #1: Console API Unavailability in Wasm

The first hurdle we encountered was the absence of the console API in Wasm. In Kermit, we had the ConsoleActual object in JS, utilizing the console API to log data to the browser's console. To address this, we took the following steps:

Converted the ConsoleActual object to an expect object, establishing a mandatory object for JS and Wasm:

expect object ConsoleActual : ConsoleIntf

Moved the existing object with console calls to jsMain and created a new one for wasmMain.

Problem #2: Wasm-JS Interop Limitations

To call console from Wasm, we needed to invoke JavaScript from Wasm. While the usual js() for inline JavaScript works for JS, Wasm required a different approach. The @JSFun annotation proved useful, allowing us to execute JavaScript functions from Wasm. However, we encountered a problem with use of Any? in the interface methods:

Wasm.ConsoleActual.kt

@JsFun("(output) => console.error(output)")
external fun consoleError(vararg output: Any?)

internal actual object ConsoleActual : ConsoleIntf {
    override fun error(vararg output: Any?) {
        consoleError(*output)
    }
}

Unfortunately, an inline error surfaced:

Type Any? cannot be used in an external function parameter. Only external, primitive, string, and function types are supported in Kotlin/Wasm JS interop.

To circumvent this limitation, we opted for a design change, using String instead of Any? for both JS and Wasm, as they share the same interface:

internal interface ConsoleIntf {
    fun error(o: String)
    // other methods...
}

This adjustment allowed smooth interaction between Wasm and JS, ensuring compatibility with the restricted set of supported APIs in Kotlin/Wasm.

Step #4 - Integration

Drawing inspiration from Kotlin's wasm-browser-sample, we created the wasm-browser sample app. It mirrors the module structure of the app-browser app in our Kotlin/JS sample.

Lessons Learned

Our foray into Kotlin/Wasm integration was not without challenges. Key takeaways include:

Interoperability with JS is a work in progress, requiring careful consideration when sharing code between the two.
Loading generated .wasm files directly in web apps may pose challenges, especially around types. We couldn't get this to work in the short time we had.
Debugging Wasm-related issues can be tricky; Our tests failure output wasn't easy to understand. Kotlin Slack proved to be an invaluable resource for troubleshooting. We learned that output with --info flag shows the actual node command that's being executed. Calling that command directly showed better errors and we could fix the code then.
Compatibility concerns arise regarding the version of Node.js; Note that versions 1.9.20 onwards would require Node version and Browsers that support Wasm GC.

Feel free to explore the latest version of Kermit and dive into the exciting world of Kotlin/Wasm. Stay tuned for future updates and enhancements! Share your experiences and questions with us on #touchlab-tools channel on Kotlin Slack. Also, you can reach out to me at @shaktiman_droid on Twitter(X) or LinkedIn. Happy coding!

Logger.i() Not Your Style? Customize Kermit Logger!

Jigar Brahmbhatt — Tue, 24 Oct 2023 02:19:28 +0000

In the realm of Kotlin Multiplatform logging, the Kermit library stands as a trusted companion for developers. However, some find its conventional logger.i syntax less appealing. What if you could improve your logging experience with a touch of personalization? Enter the world of custom logger, where logger.info becomes a reality.

Diving into Custom Logging

The journey begins with a glance at a custom code snippet that transforms the Kermit logging experience. This code introduces a custom Logger class adorned with methods like info, and error—a testament to the flexibility Kermit provides for tailoring logging to your liking.

Note that example code below is a very toned down version of full Logger API. It helps with keeping the code minimal while still delivering the idea behind it.

import co.touchlab.kermit.BaseLogger
import co.touchlab.kermit.LoggerConfig
import co.touchlab.kermit.Severity
import co.touchlab.kermit.mutableLoggerConfigInit
import co.touchlab.kermit.platformLogWriter

open class Logger(
    config: LoggerConfig,
    open val tag: String = "MyDefaultTag"
) : BaseLogger(config) {
    inline fun info(throwable: Throwable? = null, tag: String = this.tag, message: () -> String) {
        logBlock(Info, tag, throwable, message)
    }

    inline fun error(throwable: Throwable? = null, tag: String = this.tag, message: () -> String) {
        logBlock(Error, tag, throwable, message)
    }

    inline fun info(messageString: String, throwable: Throwable? = null, tag: String = this.tag) {
        log(Info, tag, throwable, messageString)
    }

    inline fun error(messageString: String, throwable: Throwable? = null, tag: String = this.tag) {
        log(Error, tag, throwable, messageString)
    }

    companion object : Logger(mutableLoggerConfigInit(listOf(platformLogWriter())))
}

Now instead of calling Kermit's API, you can call your own methods.

Call

Logger.info(...)

rather than

Logger.i(...)

Kermit-core

This flexiblity comes from the modularized kermit components. If you prefer to have custom logger then you need to only depends on kermit-core instead of kermit

implementation "co.touchlab:kermit-core:{{KERMIT_VERSION}}"

Beyond syntax preferences, custom logger methods may include more flexibility matching your application's unique needs.

Embrace the power of custom logging with Kermit, and let your logs echo your coding identity. Happy logging!

Let me know in the comments if you have questions. Also, you can reach out to me at @shaktiman_droid on Twitter(X), LinkedIn or #touchlab-tools channel on Kotlin Slack. And if you find all this interesting, maybe you'd like to work with or work at Touchlab.

Optimizing Gradle Builds in Multi-module Projects

Jigar Brahmbhatt — Mon, 16 Oct 2023 20:31:31 +0000

You're not alone if you've also struggled with sluggish Gradle builds in a multi-module project. Recently, we undertook the challenge of significantly reducing build times for a client with over 100 Kotlin Multiplatform modules, and achieved a more than 50% boost in speed across platforms. In this post, we'll walk you through the steps we took. We hope it proves valuable to fellow developers facing similar challenges.

Benchmark Your Builds

Before diving into optimizations, it's crucial to understand the baseline. Gather build times from all team members, ensuring the Gradle build cache is disabled. Use handy --no-build-cache option to any Gradle task command to run without build cache. Unsurprisingly, in our case, the Intel-based mac machines were really slow compared to Apple chip ones and we didn't have anyone with a Windows machine. This information is key for later comparison and improvement assessment.

Note: One thing we realized that, some optimizations below might be more applicable to legacy or tech-debt-laden projects.

Tools for Insight

Gradle Build Scan

Utilize the power of Gradle Build Scan to delve into the details of your builds. In my opinion, it's not just a diagnostic tool; it's a learning tool.

In our case, we uncovered insights into the sluggishness of ios link tasks in the Kotlin Multiplatform setup. Comparing build scans on different CI machines helped identify the fastest configuration for a machine to use on our CI. Enabling parallel builds and analyzing the results through build scan reports further validated our improvements.

Android Studio Build Analyser

Android Studio provides a built-in analyser tool. It inspects build performance and provides warning around potential issues.

Disable Jetifier

Using this, we noticed the lingering android.enableJetifier=true usage due to outdated Picasso library that didn't use AndroidX libraries. That might have hindered build speed too. Addressing this involved updating Picasso and removing the jetifier flag from gradle.properties.

MultiDex

Through the Build Analyser, we also found unnecessary use of multiDexEnabled in few modules along with some old Gradle configurations. MultiDex was unnecessary with minSdkVersion as 21.

Dependency Visibility

We observed a significant number of modules relying on other modules via api dependency. The problem with having api dependencies is that Gradle would recompile them when implementation details change. It's because they appear on compile classpaths. This can have significant ripple of recompilations in a multi-module setup and affect the build times.

To mitigate this, we shifted to using implementation for most dependencies, reserving api only for those exported as part of XCFramework.

Enable Gradle Parallel Execution

In a multi-subproject setup, Gradle may benefit greatly from parallel execution. With the shift from api to implementation, enabling parallel execution further slashed build times.

Mindful Use of External Gradle Plugins

Some Gradle plugins can be the culprits behind slower builds. Our project had a couple of Gradle plugins like that. They used to execute on every sync, every task and run through all the modules in the project.

Scrutinize third-party plugins before integration, especially in a multi-module setup. Avoid unnecessary global application using subproject or allprojects blocks; apply plugins only where needed.

Unnecessary KMP targets

When managing Kotlin Multiplatform (KMP) projects, it's crucial to evaluate the necessity of added KMP targets. In our experience, we found that inadvertently adding targets that aren't required for the project can introduce inefficiencies.

For instance, we had inherited some modules with added JVM targets for certain KMP modules from older test modules. Over time, more modules were introduced, and the JVM target persisted without any actual use. This led to unnecessary JVM-related build and test tasks executing during the build phase.

To address this, we recommend reviewing your KMP setup and removing any targets that don't contribute to the project's functionality. This not only streamlines the build process but also reduces unnecessary overhead, especially in a large multi-module project like ours.

Build only required XCFramework

In Kotlin Multiplatform (KMP) projects with iOS components, the iOS build task can be a significant contributor to extended build times. Often, KMP project script files include configurations for multiple iOS architectures using iOSX64(), iosArm64(), and iosSimulatorArm64() targets, or the shorthand ios() that enables both iosArm64 and iOSX64.

However, it's essential to optimize this setup, especially considering that building for unnecessary architectures can consume substantial time and resources. For example, even if your local development machine has an ARM architecture, building the X64 framework unnecessarily adds to build times, and vice versa for other architectures.

Generally speaking, if things work on one architecture, then it's high likely that it would work on other architectures too. So it's fine if you at least keep building only one architecture locally. One approach is to introduce a boolean flag in your gradle.properties file, creating custom logic to enable a specific iOS target.

Are you on a team where not everybody calling the Kotlin code wants or needs to build it locally? We've built KMMBridge, a tool to help streamline the iOS dev flow in KMP.

Be Careful with Custom Gradle Tasks

While creating custom Gradle tasks might seem like a convenient way to handle common requirements, it's crucial to exercise caution, especially in a multi-module setup. In our experience, some custom tasks had unintended consequences on build times.

For instance, we had custom tasks responsible for copying resources to another folder, but they ran across all modules, resulting in a noticeable slowdown during the build. To address this issue, we reconsidered our approach and opted for a different strategy to achieve the desired outcome without compromising build efficiency.

The key takeaway is to ensure that custom tasks are appropriately configured to avoid unnecessary repetition across modules or tasks

Keep build tools up-to-date

Always stay current with Android Studio, Android Gradle Plugin, and Gradle itself. Each iteration brings improvements, potentially enhancing build speed.

AGP 8.+

Upgrade to Android Gradle Plugin 8.0.0 for default behaviors that optimize builds (i.e. non-transitive R classes), especially for apps with multiple modules.

Configuration Cache

Newer build tools have better support for configuration cache. It seems like a very promising feature that can drastically improve build speeds in certain cases.

While configuration cache is a promising feature for faster builds, ensure compatibility with all your tools. As of Kotlin 1.9.10, the Kotlin Multiplatform plugin still lacks full support, limiting its effectiveness.

Kotlin 1.9.20 is supposed to being full support for configuration cache. We're pretty pumped about it.

Additional Considerations

Ensure Gradle Build Cache is enabled.
Amount of code can be overwhelming in Gradle files with multi-module setup. Simplify Gradle scripts using the Gradle convention plugin to minimize duplicate configuration.

By following these steps, you may turbocharge your Gradle builds, regardless of the project size or complexity. Happy coding! Let me know in the comments if you have questions. Also, you can reach out to me at @shaktiman_droid on Twitter, LinkedIn or Kotlin Slack. And if you find all this interesting, maybe you'd like to work with or work at Touchlab.

Jetpack Compose: A use case for view interop migration strategy

Jigar Brahmbhatt — Mon, 13 Feb 2023 17:59:33 +0000

Approach

Recently, we had an opportunity to redesign the sample app for an SDK we're developing. We were only redesigning one screen (home page), so we decided to introduce Jetpack Compose in the app.

Based on what we read, most migration or view interop posts are about keeping Fragments and fragment navigation as they are and moving the content of the fragments into ComposeView. In fact, official docs also mention that strategy.

For that, we would still have to touch other fragments in the app rather than just the home page. So it felt like more work than what we intended to do. On top of that, the sample app extensively uses PreferenceFragmentCompat for various setting screens. To move its content to ComposeView, we would have to re-create a kind of preferences screen from scratch because compose doesn't have a straight replacement for PreferenceFragment.

So we decided to go with the Fragments in Compose approach. Along with that, we also moved our navigation using compose navigation component.

Fragments in Compose

Layout

We created new layout files for each fragment with FragmentContainerView in each.

<?xml version="1.0" encoding="utf-8"?>
<androidx.fragment.app.FragmentContainerView xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/fragment_container_view_events"
    android:name="com.example.fragment.analytics.AnalyticsEventsFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

</androidx.fragment.app.FragmentContainerView>

Composable

We wrote a generic FragmentHolder composable with AndroidViewBinding. It composes an Android layout resource. The layout files we created above would have their Binding class generated that we can inflate and pass as BindingFactory in the AndroidViewBinding

@Composable
fun <T : ViewBinding> FragmentHolderScreen(
    topBarTitle: String,
    androidViewBindingFactory: (inflater: LayoutInflater, parent: ViewGroup, attachToParent: Boolean) -> T,
    onBackPress: () -> Unit = {},
    androidViewBindingUpdate: T.() -> Unit = {},
) {
    Scaffold(
        topBar = {
            TopBar(title = topBarTitle, onBackPress = onBackPress)
        },
        content = { paddingValues ->
            AndroidViewBinding(
                factory = androidViewBindingFactory,
                modifier = Modifier.padding(paddingValues),
                update = androidViewBindingUpdate,
            )
        },
    )
}

Navigation

After creating the composable, we defined a navigation component with a Screen enum.

With above defined layout binding and FragmentHolderScreen for AnalyticsEventsFragment, the minimized Scaffold composables look like this,

Scaffold(
    content = { contentPadding ->
        NavHost(
            navController = navController,
            startDestination = Screen.Settings.route,
            Modifier.padding(contentPadding),
        ) {
            composable(Screen.Events.route) {
                FragmentHolderScreen(
                    topBarTitle = getString(R.string.toolbar_title_events),
                    androidViewBindingFactory = ComposeFragmentEventsBinding::inflate,
                    androidViewBindingUpdate = {
                        with(fragmentContainerViewEvents.getFragment<AnalyticsEventsFragment>()) {
                            // Reference of AnalyticsEventsFragment is available here
                        }
                    },
                    onBackPress = {
                        onBackPress(navController)
                    },
                )
            }
        }
    },
)

Inner/child fragments

Some of our fragments internally had navigation where a user would go to child fragments. While doing the compose-based navigation, we added those child fragments as part of our Screen/route enum. Then, we set a lambda function (val navigateTo: (Screen) -> Unit) in the base fragment class to handle the click actions to move to child fragments.

SharedPreferences

The sample app uses SharedPreferences, and we didn't have time to move to something like DataStore. It still worked out well after moving one screen to Compose. We just made sure to define the reference of SharedPreferences in onCreate of the main activity and then pass the reference down to composable. Since we didn't touch existing fragments, they use the SharedPreferences as defined already.

UI Testing

We have extensive UI testing in the sample app that tests the SDK. After moving the sample app's home screen to Compose, we broke the entry point of all our tests.

Luckily, compose UI testing and espresso testing work well with each other. You can write a compose test in one-line testing the compose-based screen, and the second line can be an espresso test step looking at the view layer.

The biggest problem we faced around updating unit tests was the delay between the two systems. After clicking on a button on the compose-based screen, the app would go to SDK (a view-based UI). Many tests failed because the view would not be available on the screen when a test executes. After trying out several things, nothing worked well except adding Thread.sleep() just before and after we handle button clicks on the compose-based screen. The delay probably gave espresso enough time to find the correct view-based screen.

Conclusion

Overall, we're satisfied with how the whole experiment went. We learned a bit about compose-view interop and got the opportunity to share our findings via this blog post.

Thanks for reading! Let me know in the comments if you have questions. Also, you can reach out to me at @shaktiman_droid on Twitter, LinkedIn or Kotlin Slack. And if you find all this interesting, maybe you'd like to work with or work at Touchlab.

KMM: A Use case for common UI behavior

Jigar Brahmbhatt — Mon, 30 Jan 2023 20:03:37 +0000

This post demonstrates how we used common KMP code for a common UI feature across three platforms.

Requirement

Recently, we got a new feature requirement for the SDK we're developing using Kotlin Multiplatform (KMP). The SDK has a typical UI form with a variety of fields in it that the user fills out. One of the fields is a phone number field. The requirement was to auto-format the number as the user types it out. The end behavior would be like this,

How we did it initially

We usually divide KMP work based on UI stories for each platform and a task for any required work in the commonMain layer.

For deeper dive into how we divide KMP work, checkout Kevin's post about it

Following the same approach, first, we added a couple of utility methods in common code to format and unformat the phone number.

commonMain

fun formatPhoneNumber(number: String): String {
    // return formatted number using regex
}

fun unformatPhoneNumber(number: CharSequence): String {
    // return unformatted number using regex
}

Then we worked on individual platform UI implementation.

Android

We implemented a custom TextWatcher and handled the logic in beforeTextChanged and afterTextChanged methods.

iOS

On iOS, we used @objc func textFieldDidChange(_ sender: UITextField) to handle formatting while entering the number entering, and func textField() with the shouldChangeCharactersIn option to format the number when deleting.

Web

On ReactJS, we used onChange of the TextField to implement custom logic for formatting.

What worked and what went wrong

What worked was that each platform performed the same for the general use case of entering and deleting the number due to having common knowledge and JIRA tickets for them.

What differed between each platform was how the individual developer approached edge cases around entering and deleting the input from a specific cursor position.

For example, consider the input like this (123) 456-7890. Now user wants to remove the number 6 and manually sets the cursor position after the dash(-) like this (123) 456-|7890. Once the user presses the delete key, the number 6 should be removed, and the new cursor should get positioned after the number 5 like this (123) 45|7-890.

This logic got more complex as we found more and more edge cases at different cursor positions.

What went wrong with our approach was that we started fixing these edge cases on each platform because each had unique bugs.

`common` code at the rescue

While fixing those edge cases on each platform, we noticed a pattern in all implementations. We were ultimately doing some string manipulation based on the current cursor position to determine a new string to show on the screen along with the new cursor position.

We realized an opportunity to combine the logic in common code by just introducing methods that would take existing text and cursor position as inputs and provide a new string and a cursor position back.

After doing a refactoring exercise for that, we came up with two methods,

/**
 * @param lastCursorIndex 0-based index
 */
@JsExport
fun getTextAndCursorPositionOnTelephoneEnter(
    lastCursorIndex: Int,
    newText: String,
): TelephoneFormattingResult

/**
 * @param deletedCharIndex 0-based index
 */
@JsExport
fun getTextAndCursorPositionOnTelephoneDelete(
    deletedCharIndex: Int,
    oldText: String
): TelephoneFormattingResult

@JsExport
class TelephoneFormattingResult(
    @JsName("text") val text: String,
    @JsName("cursorPosition") val cursorPosition: Int,
)

It wasn't that straightforward to come up with the inputs for the methods above because all three platforms have different ways of getting cursor indices. While entering, the index of the last cursor position before entering the new character worked out well. For the deletion, the index of the deleted character worked out better.

Conclusion

We learned that just because some feature is only UI related, we shouldn't jump to the conclusion that there won't be any common code.

In fact, for the feature mentioned in this post, in the end, we had the most crucial logic implemented in the common code. Now, each platform's implementation remains bare-bones, where we use platform-specific APIs to extract existing text/position and rely on common logic to determine new text and cursor position.

As a bonus, we could write extensive unit tests for the common logic to cover all the edge cases. On top of that, we would have only one implementation to modify if we ever decide to change the functionality of this feature or find a bug.

Samples of Using KMMBridge

Michael Friend — Wed, 30 Nov 2022 20:46:11 +0000

What is KMM Bridge?

KMMBridge is a Gradle plugin by Touchlab that aims to simplify the process of pushing a Kotlin Multiplatform SDK binary to a remote repo to allow iOS developers to use the shared SDK without installing the Kotlin toolchain or building the Kotlin code on every app build.

What is this Sample?

This sample project showcases our typical project setup for adding Kotlin Multiplatform Mobile code to existing separate Android and iOS apps using KMMBridge. We keep the Android app and the shared code in the same repo and keep the code to an absolute minimum with no dependencies so the project will build faster to speed things up when playing around with custom publish config. To see how to set up a project that keeps the Android app in a separate repo and uses a more realistic structure in shared code, check out the article Quickstart Guide to KMMBridge

Sample Repos

The basic KMMBridge sample is split into four repos rather than being a monorepo to emulate the trend we've seen from teams adopting KMM into existing apps by publishing a KMM library from one repo for iOS apps in other repos to consume.
The four repos are:

KMMBridgeSampleKotlin aka Kotlin Repo - This is the Kotlin repo with the shared SDK code as well as an Android app that uses it.
KMMBridgeSampleCocoaPods aka CocoaPods Repo- a repo that pulls down the sdk with CocoaPods to use in an iOS app
KMMBridgeSampleSpm aka SPM Repo - a repo that pulls down the sdk with Swift Package Manager to use in an iOS app
PublicPodspecs aka Podspec Repo - A CocoaPods custom Podspec repo. When publishing for CocoaPods a podspec file will be pushed to this repo in a folder with the version number. See the CocoaPods section for more info on this.

KMMBridgeSampleKotlin - The Kotlin Code

This repo demonstrates the usual first step for a larger team that wants to try out Kotlin Multiplatform: putting new or existing Kotlin code in a shared module in your Android app repo. This repo also has a standard Android app module
that depends on the shared code through a Gradle project dependency.

The shared module is a Kotlin Multiplatform module and targets android, ios, and iosSimulatorArm64; declared in the kotlin block of the build.gradle.kts.

In the kmmbridge config block, we set publishing both with both Swift Package Manager and Cocoapods. For your project you can just include one or the other based on your team's needs. It also uses githubReleaseVersions to autoincrement versions when publishing a framework. Look over the docs for more configuration options.

addGithubPackagesRepository()
kmmbridge {
    mavenPublishArtifacts()
    githubReleaseVersions()
    spm()
    cocoapods("git@github.com:touchlab/PublicPodspecs.git")
    versionPrefix.set("0.6")
}

Publishing Changes to Kotlin Code

Since this publishes frameworks to our GitHub org, you'll need to fork the repo in order to publish changes. If you're only
using SPM and remove the CocoaPods publishing, this should be enough to start publishing your changes. If you want to use
CocoaPods you'll also need to fork the Podspec Repo and change the URL passed to the cocoapods(...) config above to your repo. You'll also have to set up deploy keys as secrets in your KMM repo. See Here for instructions on that.

Once these steps are done you should be able to publish a new version of the SDK by manually running the publish job by going to the Actions tab, selecting, KMM Bridge Publish Release and clicking Run workflow.

Using KMM Code from iOS

Configure Access

To pull down the binary and build your iOS app you'll need to configure authentication with GitHub Packages. This can either be done in your ~/.netrc file or through Mac's Keychain Access.

Either way you'll need to generate a GitHub Personal Access Token (PAT) with repo access and read:packages.

Once you get a PAT string from that, create or open ~/.netrc and add this with your username and the PAT that was created:

machine maven.pkg.github.com
  login [your username]
  password [your PAT]

If you want to use Mac's keychain to manage access, check out this blog post for more details on setting that up.

SPM

Since the base KMM repo is public, you should be able to clone the spm sample repo and run it. When you build the app it will look at the Package.swift file in the root of the Kotlin module to get the url
for the most recent version of the SDK then it will download the framework from that URL and include it in the project's build.

Getting Remote Changes

To get changes to the Kotlin code you made in your fork of the repo, you'll have to change the SPM dependency to that repo.
To do this first remove the existing dependency by selecting the project, clicking Package Dependencies, clicking the package, and hitting the minus button.

Next, add your repo as a new dependency by clicking the plus button, pasting your repo URL in the search bar, and clicking
Add Package. Double-check the version rules to make sure it will grab the version you want.

If you've already run the publish job in the Kotlin repo, SPM should pull the SDK in with your changes, assuming you selected the version correctly. If you publish a new version and want to pull it, you can right-click shared in the sidebar and click Update Package
to pull in the most recent version.

If you want to build the Kotlin code locally and test in the iOS app without publishing every change, check out this document on the SPM local dev flow.

Cocoapods

To run the CocoaPod based iOS app, clone the sample repo and
run pod install in the root of the repo to download the SDK, then open the xcworkspace file and run the app. pod install will look in https://github.com/touchlab/PublicPodspecs for a podspec matching the version specified in the Podfile and
download the framework it points to.

Getting Remote Changes

To pull in changes you made to the Kotlin code with CocoaPods, you'll need to edit the Podfile to point to the Podspec repo
you created. Then run pod update again and reopen your workspace file. We use ~> 0.6.0 to tell CocoaPods to use the highest version above 0.6.0 up to but not including version 0.7.0. Since we set the version prefix to 0.6.0 in the kmmbridge config and automatic versioning, every publish will get a new patch version for CocoaPods to recognize.

source '<YOUR PODSPEC REPO>'

target 'KMMBridgeSampleCocoaPods' do
  if ENV.include?("LOCAL_KOTLIN_PATH")
    pod 'shared', :path => ENV["LOCAL_KOTLIN_PATH"]
  else
    pod 'shared', '~> 0.6.0'
  end
end

To build and test Kotlin changes locally with CocoaPods, check out this doc
on the CocoaPods local dev flow.

If you have questions, don’t hesitate to reach out! You can head over to #touchlab-tools on the kotlinlang Slack or fill out the Contact Us form on the site. We look forward to hearing from you!

Introducing KMMBridge For Teams

Touchlab — Mon, 10 Oct 2022 19:25:17 +0000

Introducing KMMBridge for Teams

Today we are announcing KMMBridge, part of Touchlab’s new Faktory¹ tooling suite. This set of build tools allows mobile teams to successfully publish shared code faster than ever with Kotlin Multiplatform Mobile. Specifically targeted at iOS publishing, teams can now implement the Internal SDK Flow approach, today’s best practice to quickly integrate KMM into production app builds. To try it for yourself, visit https://github.com/touchlab/KMMBridge

KMMBridge allows teams to publish and integrate Kotlin Multiplatform Mobile (KMM) Xcode Frameworks as an internal SDK.

When you're ready, head to our Quickstart Guide to KMMBridge to get started!

Why We Built a Team-Focused Tool

Touchlab has spent years working with teams at different stages of their Kotlin Multiplatform journey. Evaluating KMP, putting KMP into production, and yes, even a fair bit of time talking to teams who looked at KMP and decided against it. One of the key lessons we’ve learned seems obvious in retrospect.

Different types of teams work in different ways.

Of course, every team is different. Every situation will be different. However, there are common patterns. Out of the box, the KMP and the Kotlin/Native toolkit will let you build an Xcode Framework, then integrate it locally into your Xcode project. This works well if everybody on the team builds Kotlin. And in an ideal world, everybody would be able to build Kotlin. But in the real world, most teams who have succeeded followed the Internal SDK Flow approach.

The Internal SDK Flow Approach

As with adopting any technology on a team, early wins help build momentum and confidence so the team can unlock the full potential over time. The Internal SDK Flow has emerged as the best practice to get faster ROI when adopting KMM. At its simplest, this approach means the Kotlin Xcode Framework is pre-built and published as an internal SDK (a private module shared with your team) so iOS developers can include it without building Kotlin locally.

The Kotlin Xcode Framework is pre-built and published as an internal SDK

Somebody else (a team member, CI, etc.) builds the Kotlin Xcode Framework and publishes it somewhere internal. That Framework is then consumed by Xcode just like any other SDK. The iOS build workflow does not need to add Gradle or Kotlin and does not add to its build time or risk. Our build tools let teams build their way immediately, increasing efficiency and eliminating unnecessary complexity to get started. For more context, see Nate Ebel’s talk from Droidcon NYC 2022: Adopting Kotlin Multiplatform in Brownfield Applications. It's a very good overview of the startup issues teams face.

How KMMBridge Works

KMMBridge is a set of Gradle tools that integrate with your Kotlin Multiplatform Mobile project to assist with building and publishing KMM Xcode Frameworks. It is built for the Internal SDK Flow, but you can also use it to publish public SDKs as well. The basic flow is as follows:

Edit and test your shared Kotlin code, then push to your source control repo
Kick off a CI build with KMMBridge. It packages, versions, and publishes your Xcode Framework
Tell Xcode to update to the new version

The iOS build workflow does not need to add Gradle or Kotlin and does not add to its build time or risk

For iOS devs, there is no need to install or learn anything new. KMMBridge supports Cocoapods and Swift Package Manager. It can publish to a few different back ends out of the box, including Github Releases, with more support coming soon.

Why Use This Approach?

As a leader or a member of a mid-sized-plus mobile team, does any of this sound familiar?

Most of the Android devs don’t know much about iOS builds
Most of the iOS devs have never touched Gradle²
The apps are in separate repos or at least have very different build workflows

Every team that Touchlab has worked with, that has successfully added KMP to their existing iOS app, has started with an internal SDK flow.

Some teams have relatively sophisticated internal module-sharing systems, Artifactory or similar. Most (and you’d be surprised at who) have nothing like that. Even with some kind of artifact sharing in place, there is a lot of custom work that would need to be done to wire up Kotlin Xcode Frameworks to be included into a production iOS build.

KMMBridge will help most teams speed past this and get started productively with KMM.

What Comes After the Internal SDK Flow?

What is the next step when you want to scale and get shared code closer to your feature dev flow?

It can seem simple on the surface but this can get tricky, depending on team structure and how features are developed. One example we’ve seen a bit of: over time both teams could start to edit the code as if it wasn’t shared, and without clear guidance those edits can start to conflict in multiple ways.

Most teams with Kotlin Multiplatform Mobile in production have used one or more Touchlab solutions. If you are looking to scale your KMM dev (or have already done so), we should chat.

When you're ready, head to our Quickstart Guide to KMMBridge to get started!

There is more to the Faktory tooling that is in the works, but we decided to carve out this bit now as it is a necessary entry point for teams adopting KMM. As KMM enters Beta, for continued growth and adoption, there are core capabilities that simply need to exist, and the internal SDK flow is one of them._ ↩
Most Android devs try to avoid it, me included (no offense Gradle)_ ↩

Different ways to distribute and integrate Kotlin/JS library

Jigar Brahmbhatt — Mon, 11 Jul 2022 20:24:11 +0000

Note that examples in this post use Kotlin 1.7.0

In the previous post in the Kotlin/JS series, we learned about @JsExport to expose Kotlin code on the JS side. Now, we would look at various ways to distribute a JS library code through a KMP setup.

Gradle Setup
- Webpack
- Node Module
  - npm-publish
Using the library
- Use webpack executable
  - HTML
  - JavaScript
  - TypeScript
- Use as node module
  - HTML
  - JavaScript
  - TypeScript

Gradle Setup

If you don't already have a JS target in your KMP library project, then you should check out this blog post first.

Let's look at common options to use for JS target,

js(IR) {
    browser()
    nodejs()
    binaries.library()
    binaries.executable()
}

browser()
It sets the JavaScript target execution environment as browser. It provides a Gradle task—jsBrowserTest that runs all js tests inside the browser using karma and webpack.
nodejs()
It sets the JavaScript target execution environment as nodejs. It provides a Gradle task—jsNodeTest that runs all js tests inside nodejs using the built-in test framework.

binaries.library()
It tells the Kotlin compiler to produce Kotlin/JS code as a distributable node library. Depending on which target you've used along with this, you would get Gradle tasks to generate library distribution files.

Kotlin browser tasks
--------------------
jsBrowserDevelopmentLibraryDistribution
jsBrowserDevelopmentLibraryPrepare
jsBrowserProductionLibraryDistribution
jsBrowserProductionLibraryPrepare

Kotlin node tasks
-----------------
jsNodeDevelopmentLibraryDistribution
jsNodeDevelopmentLibraryPrepare
jsNodeDevelopmentRun
jsNodeProductionLibraryDistribution
jsNodeProductionLibraryPrepare
jsNodeProductionRun
jsNodeRun

EitherjsBrowserProductionLibraryDistribution or jsNodeProductionLibraryDistribution task generates output files in <YourLibModule>/build/productionLibrary folder

binaries.executable()
It tells the Kotlin compiler to produce Kotlin/JS code as webpack executable .js files. Enabling this option generates the following Gradle tasks with the browser() environment.

jsBrowserDevelopmentExecutableDistributeResources
jsBrowserDevelopmentExecutableDistribution
jsBrowserDevelopmentRun - start development webpack dev server
jsBrowserDevelopmentWebpack - build webpack development bundle
jsBrowserDistribution
jsBrowserProductionExecutableDistributeResources
jsBrowserProductionRun - start production webpack dev server
jsBrowserProductionWebpack - build webpack production bundle
jsBrowserRun
jsBrowserWebpack

Task jsBrowserDistribution generates webpack bundle js file along with .map file in <YourLibModule>/build/distributions folder.

Webpack

Webpack is a JS bundler tool. It allows the creation of a single executable JS file combining all the dependencies.

As seen above in the Gradle setup section, you can output your Kotlin/JS library as a single executable by using browser() and binaries.executable() options in js(IR) target. By default, the bundle .js file and exported library name are the same as the module name. For example, for a module named shared, a shared.js file gets generated. It would have exports.shared=... that reflects the name of the library that one would use when consuming this library in a JS/TS app.

....."object"==typeof exports?exports.shared=n().....

The browser() function provides a DSL that you can use to update KotlinWebpack task for various custom configurations. For example, you can change the file and library name as below,

browser {
    webpackTask {
        outputFileName = "kmp_lib.js"
        output.library = "kmpLib"
    }
}

You can explore more options on your own.

Node Module

Kotlin/JS library can also be published as a node module, and installed via npm in an app.

As mentioned above in the Gradle setup section, when you run jsNodeProductionLibraryDistribution, it generates the following node-module related files,
- .js file each for the library and all dependencies
- .js.map file for each .js file
- Typescript .d.ts file
- package.json

Note that node module cannot have upper case character in the name. An error or warning may appear if the module name has a capital character. We can declare a moduleName in the js(IR) target to avoid that,

js(IR) {
    moduleName = "kmp-lib"
    ....
}

`npm-publish` plugin

By default, there is no quick way to publish the library output as a node module to maven.

npm-publish is a popular library by Martynas Petuška that helps with NPM publishing. It also provides various configuration options under the npmPublish Gradle task.

The plugin generates a tarball that we can use to install the library locally without publishing first. The packJsPackage task also logs a readable output of tarball content and details.

npm notice 
npm notice 📦  shared@0.1.0
npm notice === Tarball Contents === 
npm notice 291B  kmp-lib.d.ts                     
npm notice 1.4kB kmp-lib.js                       
npm notice 205B  kmp-lib.js.map                   
npm notice 1.4kB kotlin-kotlin-stdlib-js-ir.js    
npm notice 551B  kotlin-kotlin-stdlib-js-ir.js.map
npm notice 95B   package.json                     
npm notice === Tarball Details === 
npm notice name:          shared                                  
npm notice version:       0.1.0                                   
npm notice filename:      shared-0.1.0.tgz                        
npm notice package size:  1.6 kB                                  
npm notice unpacked size: 3.9 kB                                  
shared-0.1.0.tgz
npm notice shasum:        c3c5e0a7a6d99cf1b7632fcfc4cef2e0b9052cb2
npm notice integrity:     sha512-dZa4uNPRMjyny[...]JjzzNAiP7abHw==
npm notice total files:   6                                       
npm notice

If you're planning to publish a Kotlin/JS library as a node module, then this is a must-have plugin in your project.

Using the library

We will now look at various ways to integrate the Kotlin/JS library into web applications.

For example, we have a Greeting class and a greet() method under a package jabbar.jigariyo.kmplibrary

package jabbar.jigariyo.kmplibrary

import kotlin.js.JsExport

@JsExport
class Greeting {
    fun greet(): String {
        return "Hello, JS!"
    }
}

Use webpack executable

We will now look at using the generated webpack binary executable bundle file in HTML and react JS app.

HTML

We can simply embed the js file as a script under the <script> tag of the HTML body.

<html>

<head>
    <meta charset="utf-8">
    <title>Including a External JavaScript File</title>
</head>

<body>
    <!-- Here I have copied the js file in the root folder of this html file -->
    <script type="text/javascript" src="kmp_lib.js"></script>
    <script>
        var kmpLib = this['kmpLib'];
        var greeting = new kmpLib.jabbar.jigariyo.kmplibrary.Greeting();
        console.log(greeting.greet());
    </script>
</body>

</html>

Two important things to note here are,

Using the library name to get a reference var kmpLib = this['kmpLib']
Getting reference of Greeting class using package name after the library reference kmpLib.jabbar.jigariyo.kmplibrary.Greeting()

Once the html file is open in the browser, it would log Hello, JS! in console output.

JavaScript

For the JavaScript example, I've a React app.

To keep this simple, I've copied the distributions folder in the src directory of the React app.

As the next step, import the library module in the App.js and use it

import kmpLib from './distributions/kmp_lib';
......

const greeting = new kmpLib.jabbar.jigariyo.kmplibrary.Greeting()
console.log(greeting.greet())

function App() {
  return (
    .......
  );
}

export default App;

Once we run the app, Hello, JS! gets printed in the console and validates the integration with the library.

Note that you might have to deal with configuring eslint if using React.

TypeScript

It's not straightforward to use just a js file without typescript definitions in a Typescript app.

I have skipped this integration as it's out of scope for this post.

Use as node module

We will now look at installing and using the generated library files in a React JS and a TS app.

To install the module locally, you can do npm install <PATH>. You can either use the path to the tarball (.tgz) file generated by the npm-publish plugin or the relative path to the build/productionLibrary folder of the kmp module.

For example, the installation path for my sample looks like this,

npm install ../shared/build/productionLibrary

Once installed, the package.json would contain the library under the dependencies section,

"dependencies": {
  "kmp-lib": "file:../shared/build/productionLibrary"
}

Note here that the name is the same as the moduleName we had defined earlier in the above gradle-setup section.

HTML

Using node module in plain HTML is out of scope for this post. There are techniques to make that work if you need to go that route.

JavaScript

We should be able to import the library and use it once installed via npm

App.js

import kmpLib from 'kmp-lib';
......

const greeting = new kmpLib.jabbar.jigariyo.kmplibrary.Greeting()
console.log(greeting.greet())

function App() {
  return (
     .....
  );
}

export default App;

Once we run the app, Hello, JS! gets printed in the console and validates the integration with the library.

TypeScript

Just like the JavaScript example above, you have a reference of the library available after npm install.

Importing in Typescript is slightly different as seen below

main.ts

import * as kmpLib from 'kmp-lib';

let greeting = new kmpLib.jabbar.jigariyo.kmplibrary.Greeting()
console.log(greeting.greet())

Once we run tsc main.ts and then node main.js commands in the terminal, we would see Hello, JS! printed.

In this post, we first learned how to distribute a Kotlin/JS library as either a webpack bundle or node module. We later learned how to integrate the library in HTML, JS, or a TS app.

@JsExport guide for exposing Kotlin to JS

Jigar Brahmbhatt — Mon, 14 Mar 2022 16:19:31 +0000

Note that this post focuses on JS output for Kotlin. There is also a Typescript output (.d.ts file) with some unique issues that this post doesn't cover in detail.

In the previous post, we added Kotlin/JS support to an existing KMM library. Now, we would add code that works on the JS side.

Usage
- @ExperimentalJsExport vs @JsExport
Limitations
- Collections
- Long
- Interface
  - Solution - Using Implementation class
  - Solution - Using Expect-Actual
- Enum
- Sealed classes
- Code mangling
- Suspended functions

Usage

It is critical to understand @JsExport annotation and all the issues around it if you expose Kotlin code through Kotlin/JS as an external JS library

With the new IR compiler, Kotlin declarations do not get exposed to JavaScript by default. To make Kotlin declarations visible to JavaScript, they must be annotated with @JsExport.

Note that @JsExport is experimental as of the posted date of this post (with Kotlin 1.6.10)

Let’s start with a very basic example,



// commonMain - Greeting.kt
class Greeting {
    fun greeting(): String {
        return "Hello World!"
    }
}

At this point, the generated .js library file would not have any reference to the Greeting class. The reason is that it is missing the @JsExport annotation.

You can generate JS library code via ./gradlew jsBrowserDistribution. You would find the .js, .d.ts and map file in root/build/js/packages/<yourlibname>/kotlin folder.

Now, add the annotation to generate JS code for it,



import kotlin.js.ExperimentalJsExport
import kotlin.js.JsExport

@ExperimentalJsExport
@JsExport
class Greeting {
    fun greeting(): String {
        return "Hello World!"
    }
}

The .js and .d.ts files would now contain the Greeting reference.

Generated .js file ```javascript

function Greeting() {
}
Greeting.prototype.greeting = function () {
return 'Hello World!';
};
Greeting.$metadata$ = {
simpleName: 'Greeting',
kind: 'class',
interfaces: []
};


- **Generated .d.ts file**
```typescript


export namespace jabbar.jigariyo.kmplibrary {
    class Greeting {
        constructor();
        greeting(): string;
    }
}

Now you can call Greeting from JavaScript



console.log(new jabbar.jigariyo.kmplibrary.Greeting().greeting())
// Hello World!

Note that you would have to use fully qualified Kotlin names in JavaScript because Kotlin exposes its package structure to JavaScript.

It is important to keep in mind that all public attributes in your exportable object would also need to be exportable.

In the following example, CustomObj would also need to be exportable to export MyDataClass,



@JsExport
data class MyDataClass(
    val strVal: String,
    val customObj: CustomObj // This would need to be exportable
)

@ExperimentalJsExport vs @JsExport

@JsExport is the annotation you need to tell the compiler to generate JavaScript code, and @ExperimentalJsExport is an opt-in marker annotation to use @JsExport as it is experimental to use.

You can get rid of the requirement of adding @ExperimentalJsExport in code by declaring it as OptIn in languageSettings for all source sets in your kotlin block.



kotlin {
    sourceSets {
        all {
            languageSettings.apply {
                optIn("kotlin.js.ExperimentalJsExport")
            }
        }
    }
}

Limitations

As of Kotlin 1.6.10, there are heavy limitations on what Kotlin types one can export to JavaScript.

You will most likely face one of these limitations if you add JS support in an existing KMP library.

Whenever something is not-exportable, you would get either an error or a warning:

Code does not compile with such errors
Code compiles with such warnings, but you might have run-time issues

Collections

Kotlin's collections APIs are not exportable, so you would have to come up with different strategies to deal with them. Some examples would be:

Map

You would have to remove Map usage from common code that also exports to JS, or you would have to have a different implementation on the mobile and js side. You can use the kotlin.js.Json object on the jsMain side and then map it to the Kotlin map whenever needed.

For JS specific implementation, you may also look into using Record from kotlin-extensions library.

List

You can replace the List usage with an Array to keep the same code for all platforms. It may or may not be a simple replacement.

For example, Array would work if only used in an object for parsing an API response. Note that having an Array in a Data class would require providing your own equals and hashcode implementations.

Note that moving from List to Array might have an impact on generated code for iOS. List becomes NSArray on iOS side but Array becomes a Kotlin object wrapping the array

If you want separate implementation for jsMain, then kotlin-extensions library provides some helpful JS specific classes like Iterator, Set, and ReadOnlyArray

Long

Long is not mapped to anything as there is no equivalent in the JavaScript world. You would see the non-exportable warning if you export Long via Kotlin.

If you ignore the warning, then Long still kinda works. It just takes any value from JS. Kotlin will receive the input as Long if JavaScript code sends a BigInt.

It will not work for Typescript unless you set skipLibCheck = true in the config as type kotlin.Long is not available.



// Kotlin 
@JsExport
class Greeting {
    @Suppress("NON_EXPORTABLE_TYPE")
    fun printLong(value: Long) {
        print(value)
    }
}

// Generated .js
Greeting.prototype.printLong = function (value) {
  print(value);
  };

// Generated .d.ts
printLong(value: kotlin.Long): void;

// Usage from JS
const value = "0b11111111111111111111111111111111111111111111111111111"
Greeting().printLong(BigInt(value)) // This works

You can use @Suppress("NON_EXPORTABLE_TYPE") to suppress the exportable warning

Interface

Kotlin interfaces are not exportable. It gets annoying when a library has an interface-driven design, where it exposes the interface in public API rather than a specific implementation.

Interfaces will be exportable starting upcoming Kotlin 1.6.20! We would have to play around with that to see it working.

There are workarounds to make interfaces work on JavaScript.

The following are some examples for getting around interfaces:

Using Implementation Class



@JsExport
interface HelloInterface {
    fun hello()
}

The above code would show the non-exportable error. You can use the interface indirectly via its implementation class to work around that problem.



@JsExport
object Hello : HelloInterface {
    override fun hello() {
        console.log("HELLO from HelloInterface")
    }
}

Generated JS code for the above hello method will have a mangled name. Read more about it in code-mangling section



interface HelloInterface {
    @JsName("hello")
    fun hello()
}

@JsExport
object Hello : HelloInterface {
    override fun hello() {
        console.log("HELLO from HelloInterface")
    }
}

Similarly, here are some variations to use HelloInterface,



// Variation (2)
@JsExport
object HelloGet {
    fun getInterface(): HelloInterface {
        return Hello
    }
}

// Variation (3)
@JsExport
class HelloWrapper(@JsName("value") val value: HelloInterface)

// Variation (4)
@JsExport
data class HelloWrapperData(@JsName("value") val value: HelloInterface)

All above variations are usable from the JS side even with a non-exportable warning around interface usage,



/**
 * JS side calling code
 * (1)
 * Hello.hello()
 *
 * (2)
 * HelloGet.getInterface().hello()
 *
 * (3)
 * const wrapperObj = HelloWrapper(Hello)
 * wrapperObj.value.hello()
 *
 * (4)
 * const wrapperDataObj = HelloWrapperData(Hello)
 * wrapperDataObj.value.hello()
 */

Using Expect-Actual Pattern

Another idea for using interfaces is to use the expect-actual pattern to define a Kotlin interface in common and mobile platforms and define an external interface for the JS side. This approach might not scale well but can be very useful for simple cases.



// commonMain
expect interface Api {
    fun getProfile(callback: (Profile) -> Unit)
}

// jsMain
// Here external makes it a normal JS object in generated code
actual external interface Api {
    actual fun getProfile(callback: (Profile) -> Unit)
}

// mobileMain
actual interface Api {
    actual fun getProfile(callback: (Profile) -> Unit)
}

These examples showcase workarounds that might or might not work for a particular project.

Enum

As of Kotlin 1.6.10, enums are not exportable. It can create issues for projects that have a lot of existing enums.

Good news is that its support coming in Kotlin 1.6.20

There is also a trick to export and use enums on JS. It requires defining a JS-specific object with attributes that point to actual enums.

For example, this code won't compile,



@JsExport
enum Gender {
    MALE,
    FEMALE
}

Instead, you can do this indirectly by re-defining them through object fields. It works with a non-exportable warning. Note the warning suppression with annotation.



@Suppress("NON_EXPORTABLE_TYPE")
@ExperimentalJsExport
@JsExport
object GenderType {
    val male = Gender.MALE
    val female = Gender.FEMALE
}

Sealed classes

Sealed classes are exportable, but they’re buggy as of Kotlin 1.6.10

You can export a data or regular class as subclasses inside a Sealed class body, but not an object.



@JsExport
sealed class State {
    object Loading: State() // This won't be visible 
    data class Done(val value: String): State() // This would be visible
}

You can work around this problem by moving the subclasses outside the body of the sealed class, but then you cannot write it like State.Loading. It is more of a readability issue in that case.

Also, sealed classes have known issues with typescript binding as well.

Code mangling

The Kotlin compiler mangles the names of the functions and attributes. It can be frustrating to deal with mangled names.

For example,



@JsExport
object Hello : HelloInterface {
    override fun hello() {
        console.log("HELLO from HelloInterface")
    }
}

Generated JS code for hello method looks like,



Hello.prototype.hello_sv8swh_k$ = function () {
  console.log('HELLO from HelloInterface');
};

We would need to use the @JsName annotation to provide a generated name. If you see numbers in attribute names like _something_0, _value_3 on the JS side, then it is a sign that you need to provide a controlled name via @JsName annotation on the Kotlin side.

After adding @JsName("hello") in the above example, generated code looks like this where there is a new hello method that references hello_sv8swh_k$ internally,



Hello.prototype.hello_sv8swh_k$ = function () {
  console.log('HELLO from HelloInterface');
};
Hello.prototype.hello = function () {
  return this.hello_sv8swh_k$();
};

Note that @JsName is prohibited for overridden members, so you would need to set it to a base class property or method.

Suspended functions

You cannot expose suspended functions to JS. You would need to convert them into JavaScript Promise object.

The easiest way to do that would be to wrap suspend calls inside,



GlobalScope.promise {
  // suspend call
}

This function comes from Promise.kt in the coroutine library. It returns a generic type.

As mentioned earlier, some of these issues would get resolved with Kotlin 1.6.20, so keep that in mind.

In the next post, we will look at different ways to distribute Kotlin/JS library since we've some JS exportable code.

Forem: Touchlab

Kotlin 1.9.20: Streamlining Source Sets in Multiplatform Project

Simplified iOS Target Configuration

Streamlined Custom Source Sets

Manually apply the template

Enhanced Code Completion Support

Android instrumented test changes

Opting Out of Default Templates

Conclusion

Amper: a new way to configure Gradle projects?

How does it work?

Our Thoughts

Additional Resources

Getting Started with Compose for Web

Compose Runtime and Component Library

Creating the project

Running the project

How does this work?

Final Thoughts

Kermit Now Supports WASM

What is Kotlin/Wasm?

Kermit Steps into the Wasm Arena

Step #1 - Adding the Wasm Target

Step #2 - Common Source Set

Step #3 - Code Migration

Problem #1: Console API Unavailability in Wasm

Problem #2: Wasm-JS Interop Limitations

Step #4 - Integration

Lessons Learned

Logger.i() Not Your Style? Customize Kermit Logger!

Diving into Custom Logging

Kermit-core

Optimizing Gradle Builds in Multi-module Projects

Benchmark Your Builds

Tools for Insight

Gradle Build Scan

Android Studio Build Analyser

Dependency Visibility

Enable Gradle Parallel Execution

Mindful Use of External Gradle Plugins

Unnecessary KMP targets

Build only required XCFramework

Be Careful with Custom Gradle Tasks

Keep build tools up-to-date

Additional Considerations

Jetpack Compose: A use case for view interop migration strategy

Approach

Fragments in Compose

Layout

Composable

Navigation

Inner/child fragments

SharedPreferences

UI Testing

Conclusion

KMM: A Use case for common UI behavior

Requirement

How we did it initially

commonMain

Android

iOS

Web

What worked and what went wrong

common code at the rescue

Conclusion

Samples of Using KMMBridge

What is KMM Bridge?

What is this Sample?

Sample Repos

KMMBridgeSampleKotlin - The Kotlin Code

Publishing Changes to Kotlin Code

Using KMM Code from iOS

Configure Access

SPM

Getting Remote Changes

Cocoapods

Getting Remote Changes

Introducing KMMBridge For Teams

Introducing KMMBridge for Teams

Why We Built a Team-Focused Tool

`common` code at the rescue

`npm-publish` plugin