DEV Community: Jigar Brahmbhatt

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!

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.

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.

Add Kotlin/JS support to your KMM library

Jigar Brahmbhatt — Fri, 04 Mar 2022 22:23:52 +0000

We have been working on a few projects that need to expose Kotlin code through Kotlin/JS as an external JS library. You can add JS as an output target of an existing KMM-focused module, but there are some issues you'll need to consider that don't generally present challenges to a mobile-only project.

Note that this post assumes that you already have a Kotlin Multiplatform Mobile library project, and are planning to add Kotlin/JS support to it

A good f̵i̵r̵s̵t̵ zero-step (not a mandatory one) would be to make sure that your source sets are marked by getting as per the Kotlin Gradle DSL standards. It only applies if you use Kotlin based build scripts.

I would strongly recommend moving to Kotlin based scripts If you're still using Groovy-based Gradle build scripts

This Multiplatform Gradle DSL reference is a helpful document to follow while writing a Gradle build script for KMP.

After this step, your build script would have source sets declared as below,



kotlin {
 sourceSets {
  val commonMain by getting { /* ... */ }
 }
}

You may check out this commit where I made these changes for the KaMPKit project

Now let's move to actual steps

Step 1

Make sure that you remove any clean task from your project. Gradle's LifecycleBasePlugin already brings the clean task, so you want to avoid getting a compilation error later. You most likely have one in your root Gradle file that looks like this,



tasks.register<Delete>("clean") {
    delete(rootProject.buildDir)
}

Add the JS target block with IR compiler option to your kotlin block, and add the nodejs target and library container inside that

We will discuss both options in detail later



kotlin {
    // .... other targets
    js(IR) {
        nodejs()
        binaries.library()
    }
}

Add main and test source sets for JS



sourceSets {
    // .... other source sets
    val jsMain by getting
    val jsTest by getting {
        dependencies {
            // you don't need this if you already have
            // kotlin("test") as your `commonTest` dependency
            implementation(kotlin("test-js"))
        }
    }
}

If you sync the project now, it should sync successfully! (probably won't build yet)

Now add the actual JS source folders.

Since we've already added JS target, we can add the jsMain and jsTest directories using auto complete by right-clicking on src --> new --> Directory

Step 2

At this stage, your project might not compile if you have any code in commonMain that Kotlin/JS does not support, or if it is missing JS equivalents. ./gradlew build would most likely fail.

You now have two options,

1) Make sure all your common code compiles for JS, can be exported as JS library and add js actual for any expect declarations

2) Introduce a mobileMain source set/folder and move all the existing common code there

I would suggest going with option (2) because it is a path of the least resistance, and you would get more time to think about how you want to write JS-specific code and common code for all platforms later. You may already have a lot of existing code in commonMain with various dependencies that might not be suitable to use on JS.

Native mobile platforms, Android and iOS tend to have similar needs and capabilities like SQL, local files, threads, serialization, etc. JS/web, on the other hand, are somewhat different in what you can do and often work differently. It makes sense then that any moderately functional library will need at least consideration of the conceptual differences and quite probably another layer (mobileMain) to better separate features and dependencies between web and native mobile. The latter is generally what we recommend, because you’ll probably need to do that separation at some point anyway.

option (1) is the fallback if you have a small existing codebase that requires only a few changes to support the JS side, and if you would most likely not have any common code between android and iOS platforms.

For option 2

First, you would need to create custom source sets for mobileMain and mobileTest and make android and ios ones depend on it. Also, note that you will need to move all dependencies from commonMain to mobileMain. In short, you would want mobileMain to look like your commonMain after the change. commonMain would get emptied.

Before and after diff of mentioned changes look like this for a sample project,



     sourceSets {
-        val commonMain by getting {
-            dependencies {
-                implementation("io.ktor:ktor-client-core:$ktorVersion")
-            }
-        }
+        val commonMain by getting
         val commonTest by getting {
             dependencies {
                 implementation(kotlin("test"))
             }
         }
         val iosArm64Main by getting
         val iosSimulatorArm64Main by getting
         val iosMain by creating {
-            dependsOn(commonMain)
             iosX64Main.dependsOn(this)
             iosArm64Main.dependsOn(this)
             iosSimulatorArm64Main.dependsOn(this)
         }
         val iosArm64Test by getting
         val iosSimulatorArm64Test by getting
         val iosTest by creating {
-            dependsOn(commonTest)
             iosX64Test.dependsOn(this)
             iosArm64Test.dependsOn(this)
             iosSimulatorArm64Test.dependsOn(this)
         }
+        val mobileMain by creating {
+            dependsOn(commonMain)
+            androidMain.dependsOn(this)
+            iosMain.dependsOn(this)
+            dependencies {
+                implementation("io.ktor:ktor-client-core:$ktorVersion")
+            }
+        }
+        val mobileTest by creating {
+            dependsOn(commonTest)
+            androidTest.dependsOn(this)
+            iosTest.dependsOn(this)
+        }
         val jsMain by getting
         val jsTest by getting
     }

Next, you would add the actual folder, just like what we did for js above in step 1. Along with that, you would want to move the entire commonMain code content to mobileMain, and commonTest to mobileTest.

After this, your project should build successfully with ./gradlew build because you would not have any code in commonMain that failed before due to introduction of JS side.

Step 3

Now you're ready to work on the JS codebase.

You might end up moving some classes back from mobileMain to commonMain depending on what you want in all three platforms, but at this point you can build and test the project after every step so that you're sure nothing is breaking.

Now that you have the JS sourceSet, in the next post we will look at writing exportable code in Kotlin for JS using @JsExport

DEV Community: Jigar Brahmbhatt

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

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

Different ways to distribute and integrate Kotlin/JS library

Table Of Contents

Gradle Setup

Webpack

Node Module

npm-publish plugin

Using the library

Use webpack executable

HTML

JavaScript

TypeScript

Use as node module

HTML

JavaScript

App.js

TypeScript

main.ts

@JsExport guide for exposing Kotlin to JS

Table Of Contents

Usage

@ExperimentalJsExport vs @JsExport

Limitations

Collections

Map

List

`common` code at the rescue

`npm-publish` plugin