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.
    • , which is in particular used by the RequireJS library.
    • , 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.

    If you’re targeting the browser and want to use a different module system than UMD, you can specify the desired module type in the webpackTask configuration block. For example, to switch to CommonJS, use:

    Webpack provides two different “flavors” of CommonJS, commonjs and commonjs2, which affect the way your declarations are made available. While in most cases, you probably want commonjs2, which adds the module.exports syntax to the generated library, you can also opt for the “pure” commonjs option, which implements the CommonJS specification exactly. To learn more about the difference between commonjs and commonjs2, check here.

    If you are creating a library that will be consumed from JavaScript or a Node.js file, and want to use a different module system, the instructions are slightly different.

    To select module kind, set the moduleKind compiler option in the Gradle build script.

    1. compileKotlinJs.kotlinOptions.moduleKind = "commonjs"
    1. tasks.named<KotlinJsCompile>("compileKotlinJs").configure {
    2.     kotlinOptions.moduleKind = "commonjs"
    3. }

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

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

    1. kotlin {
    2.     js {
    4.     }
    5. }

    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”:

    You should declare it like this in Kotlin:

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

    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:

    1. @file:JsModule("extModule")
    2. package ext.jspackage.name
    4. external fun foo()
    6. external class C

    where the corresponding JavaScript module is declared like this:

    1. module.exports = {
    2.     foo:  { /* some code here */ },
    3.     C:  { /* some code here */ }
    4. }

    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 our example a bit more complicated:

    1. module.exports = {
    2.     mylib: {
    3.         pkg1: {
    4.             foo: function() { /* some code here */ },
    5.             bar: function() { /* some code here */ }
    7.             baz: function() { /* some code here */ }
    8.         }
    9.     }
    10. }

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

    1. @file:JsModule("extModule")
    2. @file:JsQualifier("mylib.pkg1")
    3. package extlib.pkg1
    5. external fun foo()
    7. external fun bar()

    and

    1. @file:JsModule("extModule")
    2. @file:JsQualifier("mylib.pkg2")
    3. package extlib.pkg2
    5. external fun baz()

    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:

    1. @JsModule("hello")
    2. @JsNonModule
    3. external fun sayHello(name: String)

    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. While for most use cases of Kotlin/JS, it is recommended to use a Gradle dependency on kotlin-stdlib-js, it is also available on NPM as the package.