JavaScript modules

You can compile your Kotlin projects to JavaScript modules for various popular module systems. We currently support the following configurations for JavaScript modules:

Unified Module Definitions (UMD), which is compatible with both AMD and CommonJS. UMD modules are also able to be executed without being imported or when no module system is present. This is the default option for the browser and nodejs targets.
Asynchronous Module Definitions (AMD), which is in particular used by the RequireJS library.
CommonJS, widely used by Node.js/npm (require function and module.exports object).
Plain. Don't compile for any module system. You can access a module by its name in the global scope.

Browser targets

If you intend to run your code in a web browser environment and want to use a module system other than UMD, you can specify the desired module type in the webpackTask configuration block. For example, to switch to CommonJS, use:

kotlin {
    js {
        browser {
            webpackTask {
                output.libraryTarget = "commonjs2"
            }
        }
        binaries.executable()
    }
}

Webpack provides two different flavors of CommonJS, commonjs and commonjs2, which affect the way your declarations are made available. In most cases, you probably want commonjs2, which adds the module.exports syntax to the generated library. Alternatively, you can also opt for the commonjs option, which adheres strictly to the CommonJS specification. To learn more about the difference between commonjs and commonjs2, see the Webpack repository.

JavaScript libraries and Node.js files

If you are creating a library for use in JavaScript or Node.js environments, and want to use a different module system, the instructions are slightly different.

Choose the target module system

To select the target module system, set the moduleKind compiler option in the Gradle build script:

tasks.withType<org.jetbrains.kotlin.gradle.targets.js.ir.KotlinJsIrLink> {
    compilerOptions.moduleKind.set(org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS)
}

compileKotlinJs.compilerOptions.moduleKind = org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS

The available values are: umd (default), commonjs, amd, plain.

In the Kotlin Gradle DSL, there is also a shortcut for setting the CommonJS module kind:

kotlin {
    js {
        useCommonJs()
        // ...
    }
}

@JsModule annotation

To tell Kotlin that an external class, package, function or property is a JavaScript module, you can use @JsModule annotation. Consider you have the following CommonJS module called "hello":

module.exports.sayHello = function (name) { alert("Hello, " + name); }

You should declare it like this in Kotlin:

@JsModule("hello")
external fun sayHello(name: String)

Apply @JsModule to packages

Some JavaScript libraries export packages (namespaces) instead of functions and classes. In terms of JavaScript, it's an object that has members that are classes, functions and properties. Importing these packages as Kotlin objects often looks unnatural. The compiler can map imported JavaScript packages to Kotlin packages, using the following notation:

@file:JsModule("extModule")

package ext.jspackage.name

external fun foo()

external class C

Where the corresponding JavaScript module is declared like this:

module.exports = {
  foo: { /* some code here */ },
  C: { /* some code here */ }
}

Files marked with @file:JsModule annotation can't declare non-external members. The example below produces a compile-time error:

@file:JsModule("extModule")

package ext.jspackage.name

external fun foo()

fun bar() = "!" + foo() + "!" // error here

Import deeper package hierarchies

In the previous example the JavaScript module exports a single package. However, some JavaScript libraries export multiple packages from within a module. This case is also supported by Kotlin, though you have to declare a new .kt file for each package you import.

For example, let's make the example a bit more complicated:

module.exports = {
  mylib: {
    pkg1: {
      foo: function () { /* some code here */ },
      bar: function () { /* some code here */ }
    },
    pkg2: {
      baz: function () { /* some code here */ }
    }
  }
}

To import this module in Kotlin, you have to write two Kotlin source files:

@file:JsModule("extModule")
@file:JsQualifier("mylib.pkg1")

package extlib.pkg1

external fun foo()

external fun bar()

and

@file:JsModule("extModule")
@file:JsQualifier("mylib.pkg2")

package extlib.pkg2

external fun baz()

@JsNonModule annotation

When a declaration is marked as @JsModule, you can't use it from Kotlin code when you don't compile it to a JavaScript module. Usually, developers distribute their libraries both as JavaScript modules and downloadable .js files that you can copy to your project's static resources and include via a <script> tag. To tell Kotlin that it's okay to use a @JsModule declaration from a non-module environment, add the @JsNonModule annotation. For example, consider the following JavaScript code:

function topLevelSayHello (name) { alert("Hello, " + name); }

if (module && module.exports) {
  module.exports = topLevelSayHello;
}

You could describe it from Kotlin as follows:

@JsModule("hello")
@JsNonModule
@JsName("topLevelSayHello")
external fun sayHello(name: String)

Module system used by the Kotlin Standard Library

Kotlin is distributed with the Kotlin/JS standard library as a single file, which is itself compiled as an UMD module, so you can use it with any module system described above. For most use cases of Kotlin/JS, it is recommended to use a Gradle dependency on kotlin-stdlib-js, which is also available on NPM as the kotlin package.

Last modified: 25 September 2024