What's new in Kotlin 2.3.0

Stable features

In previous Kotlin releases, several new language features were introduced as Experimental and Beta. The following features have now graduated to Stable in Kotlin 2.3.0:

• Support for nested type aliases

• Data-flow-based exhaustiveness checks for when expressions

Features enabled by default

In Kotlin 2.3.0, support for return statements in expression bodies with explicit return types is now enabled by default.

See the full list of Kotlin language features and proposals.

Unused return value checker

Kotlin 2.3.0 introduces the unused return value checker to help prevent ignored results. It warns you whenever an expression returns a value other than Unit or Nothing and isn't passed to a function, checked in a condition, or otherwise used.

The checker helps catch bugs where a function call produces a meaningful result that's silently dropped, which can lead to unexpected behavior or hard-to-trace issues.

Consider the following example:

In this example, a string is created but never used, so the checker reports it as an ignored result.

This feature is Experimental. To opt in, add the following compiler option to your build file:

With this option, the checker only reports ignored results from expressions that are marked, such as most functions in the Kotlin standard library.

To mark your functions, use the @MustUseReturnValues annotation to mark the scope on which you want the checker to report ignored return values.

For example, you can mark an entire file:

Alternatively, you can mark a specific class:

You can also mark your entire project by adding the following compiler option to your build file:

With this setting, Kotlin automatically treats your compiled files as if they are annotated with @MustUseReturnValues, and the checker reports all return values for your project's functions.

You can suppress warnings on specific functions by marking them with the @IgnorableReturnValue annotation. Annotate functions where ignoring the return value is common and expected, such as MutableList.add:

You can suppress a warning without marking the function itself as ignorable. To do this, assign the result to a special unnamed variable with an underscore (_):

For more information, see the feature's KEEP.

We would appreciate your feedback in YouTrack.

Explicit backing fields

Kotlin 2.3.0 introduces explicit backing fields – a new syntax for explicitly declaring the underlying field that holds a property's value, in contrast to the existing implicit backing fields.

The new explicit syntax simplifies the common backing properties pattern where a property's internal type is different from its exposed API type. For example, you might use an ArrayList while exposing it as a read-only List or a MutableList. Previously, this required an additional private property.

With explicit backing fields, the implementation type of the field is directly defined within the property's scope. This eliminates the need for a separate private property and allows the compiler to automatically perform smart casting to the backing field's type within the same private scope.

Before:

After:

This feature is Experimental. To opt in, add the following compiler option to your build file:

For more information, see the feature's KEEP.

We would appreciate your feedback in YouTrack.

Changes to context-sensitive resolution

Context-sensitive resolution is still Experimental, but we are continually improving the feature based on user feedback:

• The sealed and enclosing supertypes of the current type are now considered part of the contextual scope of the search. No other supertype scopes are considered. See the KT-77823 YouTrack issue for motivation and examples.

• When type operators and equalities are involved, the compiler now reports a warning if using context-sensitive resolution makes the resolution ambiguous. This can happen, for example, when a clashing declaration of a class is imported. See the KT-77821 YouTrack issue for motivation and examples.

See the full text of the current proposal in KEEP.

Improved interop through Swift export

Kotlin 2.3.0 further improves Kotlin's interoperability with Swift through Swift export, adding support for native enum classes and variadic function parameters.

Previously, Kotlin enums were exported as ordinary Swift classes. Now the mapping is direct, and you can use regular native Swift enums. For example:

In addition, Kotlin's vararg functions are now directly mapped to Swift's variadic function parameters.

Such functions let you pass a variable number of arguments. This is useful when you don't know the number of arguments in advance or when you want to create or pass a collection without specifying its type. For example:

C and Objective-C library import is in Beta

Support for importing C and Objective-C libraries to Kotlin/Native projects is in Beta.

Full compatibility with different versions of Kotlin, dependencies, and Xcode is still not guaranteed, but the compiler now emits better diagnostics in the event of binary compatibility issues.

The import is not stable yet, and the @ExperimentalForeignApi opt-in annotation is still necessary when using C and Objective-C libraries in your project for certain things related to C and Objective-C interoperability, including:

• Some APIs in the kotlinx.cinterop.* package, required when working with native libraries or memory.

• All declarations in native libraries, except for platform libraries.

For compatibility and to prevent you from having to change your source code, the new stability status is not reflected in the annotation name.

For more information, see Stability of C and Objective-C library import.

Default explicit names in block types for Objective-C headers

Explicit parameter names in Kotlin's function types, introduced in Kotlin 2.2.20, are now the default for Objective-C headers exported from Kotlin/Native projects. These parameter names improve autocompletion suggestions in Xcode and help avoid Clang warnings.

Consider the following Kotlin code:

Kotlin forwards the parameter names from Kotlin function types to Objective-C block types, allowing Xcode to use them in suggestions:

If you run into issues, you can disable explicit parameter names. To do that, add the following binary option to your gradle.properties file:

Please report any problems in YouTrack.

Faster build time for release tasks

Kotlin/Native has received several performance improvements in 2.3.0. They resulted in faster build times for release tasks like linkRelease*, for example linkReleaseFrameworkIosArm64.

According to our benchmarks, release builds can be up to 40% faster, depending on the project size. These improvements are most noticeable in Kotlin Multiplatform projects targeting iOS.

For more tips on improving project compilation times, see the documentation.

Changes to Apple target support

Kotlin 2.3.0 raises the minimum supported versions of Apple targets:

• For iOS and tvOS, from 12.0 to 14.0.

• For watchOS, from 5.0 to 7.0.

According to public data, usage of older versions is already very limited. This change simplifies overall Apple target maintenance for us and opens an opportunity to support Mac Catalyst in Kotlin/Native.

If you have to keep older versions in your project, add the following lines to your build file:

Note that such a setup is not guaranteed to successfully compile and can break your app during building or at runtime.

This release also takes the next step in the deprecation cycle for Intel chip-based Apple targets.

Starting with Kotlin 2.3.0, the macosX64, iosX64, tvosX64, and watchosX64 targets are demoted to support-tier 3. This means they are not guaranteed to be tested on CI, and source and binary compatibility between different compiler releases might not be provided. We plan to eventually remove support for the x86_64 Apple targets in Kotlin 2.4.0.

For more information, see Kotlin/Native target support.

Fully qualified names enabled by default

On Kotlin/Wasm targets, fully qualified names (FQNs) were not enabled by default at runtime. You had to manually enable support for the KClass.qualifiedName property to use FQNs.

Only the class name (without the package) was accessible, which caused issues for code ported from the JVM to Wasm targets or for libraries that expected fully qualified names at runtime.

In Kotlin 2.3.0, the KClass.qualifiedName property is enabled by default on Kotlin/Wasm targets. This means that FQNs are available at runtime without any additional configuration.

Enabling FQNs by default improves code portability and makes runtime errors more informative by displaying the fully qualified name.

This change does not increase the size of the compiled Wasm binary, thanks to compiler optimizations that reduce metadata by using compact storage for Latin-1 string literals.

Compact storage for Latin-1 characters

Previously, Kotlin/Wasm stored string literal data as is, meaning every character was encoded in UTF-16. This was not optimal for text containing only, or predominantly, Latin-1 characters.

Starting with Kotlin 2.3.0, the Kotlin/Wasm compiler stores string literals containing only Latin-1 characters in UTF-8 format.

This optimization significantly reduces metadata, as experiments on JetBrains' KotlinConf application have shown. It results in:

• Up to 13% smaller Wasm binaries compared to builds without the optimization.

• Up to 8% smaller Wasm binaries even when fully qualified names are enabled, compared to earlier versions that did not store them.

This compact storage is important for web environments where download and startup times matter. Additionally, this optimization removes the size barrier that previously prevented storing fully qualified names for classes and enabling KClass.qualifiedName by default.

This change is enabled by default, and no further action is required.

New exception handling proposal enabled by default for wasmWasi

Previously, Kotlin/Wasm used the legacy exception handling proposal for all targets, including wasmWasi. However, most standalone WebAssembly virtual machines (VMs) are aligning with the new version of the exception handling proposal.

Starting with Kotlin 2.3.0, the new WebAssembly exception handling proposal is enabled by default for the wasmWasi target, ensuring better compatibility with modern WebAssembly runtimes.

For the wasmWasi target, the change is safe to introduce early because applications targeting it usually run in a less diverse runtime environment (often running on a single specific VM), which is typically controlled by the user, reducing the risk of compatibility issues.

The new exception handling proposal remains off by default for the wasmJs target. You can enable it manually by using the -Xwasm-use-new-exception-proposal compiler option.

New export of suspend function with JsExport

Previously, the @JsExport annotation did not allow exporting suspend functions (or classes and interfaces containing such functions) to JavaScript. You had to manually wrap each suspend function, which was cumbersome and prone to errors.

Starting with Kotlin 2.3.0, suspend functions can be exported directly to JavaScript using the @JsExport annotation.

Enabling suspend function exports reduces boilerplate and improves interoperability between Kotlin/JS and JavaScript/TypeScript (JS/TS). Kotlin's async functions can now be called directly from JS/TS without extra code.

To enable this feature, add the following compiler option to your build.gradle.kts file:

Once enabled, classes and functions marked with the @JsExport annotation can include suspend functions without additional wrappers.

They can be consumed as regular JavaScript async functions and can be overridden as an async function, as well:

This feature is Experimental. We would appreciate your feedback in our issue tracker, YouTrack.

Usage of the BigInt64Array type to represent Kotlin's LongArray type

Previously, Kotlin/JS represented its LongArray as a JavaScript Array<bigint>. This approach worked but was not ideal for interoperability with JavaScript APIs that expect typed arrays.

Starting with this release, Kotlin/JS now uses JavaScript's built-in BigInt64Array type to represent Kotlin's LongArray values when compiling to JavaScript.

Using BigInt64Array simplifies interop with JavaScript APIs that use typed arrays. It also allows APIs that accept or return LongArray to be exported more naturally from Kotlin to JavaScript.

To enable this feature, add the following compiler option to your build.gradle.kts file:

This feature is Experimental. We would appreciate your feedback in our issue tracker, YouTrack.

Unified companion object access across JS module systems

Previously, when you exported a Kotlin interface with a companion object to JavaScript/TypeScript using the @JsExport annotation, consuming the interface in TypeScript worked differently for ES modules compared to other module systems.

As a result, you had to adjust the consumption of the output on the TypeScript side, depending on the module system.

Consider this Kotlin code:

You had to call it differently depending on the module system:

In this release, Kotlin unifies companion-object exports across all JavaScript module systems.

Now, for every module system (ES modules, CommonJS, AMD, UMD, no modules), companion objects inside interfaces are always accessed the same way (just like companions in classes):

This improvement also fixes collection interoperability. Before, collection factory functions had to be accessed differently depending on the module system:

Now, accessing collection factory functions is similar across all the module systems:

This change reduces inconsistent behavior between module systems and avoids bugs and interoperability issues.

This feature is enabled by default.

Support for @JsStatic annotations in interfaces with companion objects

Previously, the @JsStatic annotation was not allowed inside exported interfaces with companion objects.

For example, the following code would produce an error because only members of class companion objects can be annotated with @JsStatic:

In this case, you had to drop the @JsStatic annotation and access the companion from JavaScript (JS) in the following way:

Now, the @JsStatic annotation is supported in interfaces with companion objects. You can use this annotation on such companions and call the function directly from JS, just as you would for classes:

This change simplifies API consumption in JS, allows static factory methods on interfaces, and removes inconsistencies between classes and interfaces.

This feature is enabled by default.

@JsQualifier annotation allowed in individual functions and classes

Previously, you could only apply the @JsQualifierannotation at the file level, requiring all external JavaScript (JS) declarations to be placed in separate files.

Starting from Kotlin 2.3.0, you can apply the @JsQualifier annotation directly to individual functions and classes, just like the @JsModule and @JsNonModule annotations.

For example, you can now write the following external function code next to regular Kotlin declarations in the same file:

This change simplifies Kotlin/JS interop, keeps your project structure cleaner, and aligns Kotlin/JS with how other platforms handle external declarations.

This feature is enabled by default.

Support for JavaScript default exports

Previously, Kotlin/JS could not generate JavaScript's default exports from Kotlin code. Instead, Kotlin/JS only generated named exports, for example:

If you required a default export, you had to use workarounds inside the compiler, such as placing the @JsName annotation with default and a space as an argument:

Kotlin/JS now supports default exports directly through a new annotation:

When you apply this annotation to a Kotlin declaration (class, object, function, or property), the generated JavaScript automatically includes an export default statement for ES modules:

This change enables Kotlin code to conform to JavaScript conventions and is particularly important for platforms like Cloudflare Workers, or frameworks like React.lazy.

This feature is enabled by default. You only need to use the @JsExport.Default annotation.

New API for registering generated sources in Gradle projects

Kotlin 2.3.0 introduces a new Experimental API in the KotlinSourceSet interface, which you can use to register generated sources in your Gradle projects.

This new API is a quality-of-life improvement that helps IDEs distinguish between generated code and regular source files. The API allows IDEs to highlight the generated code differently in the UI and to trigger generation tasks when the project is imported. We are currently working on adding this support in IntelliJ IDEA. The API is also especially useful for third-party plugins or tools that generate code, such as KSP (Kotlin Symbol Processing).

For more information, see Register generated sources.

Improved UUID generation and parsing

Kotlin 2.3.0 introduces several improvements for the UUID API, including:

• Support for returning null when parsing invalid UUIDs

• New functions to generate v4 and v7 UUIDs

• Support for generating v7 UUIDs for specific timestamps

UUID support in the standard library is Experimental but planned to be stabilized in the future. To opt in, use the @OptIn(ExperimentalUuidApi::class) annotation or add the following compiler option to your build file:

We would appreciate your feedback in YouTrack or in the related Slack channel.