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
andnodejs
targets. - Asynchronous Module Definitions (AMD), which is in particular used by the RequireJS library.
- CommonJS, widely used by Node.js/npm (
require
function andmodule.exports
object) - Plain. Don’t compile for any module system. You can access a module by its name in the global scope.
Targeting the browser
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:
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. 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.
Creating JavaScript libraries and Node.js files
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.
Choosing the target module system
To select module kind, set the moduleKind
compiler option in the Gradle build script.
compileKotlinJs.kotlinOptions.moduleKind = "commonjs"
tasks.named<KotlinJsCompile>("compileKotlinJs").configure {
kotlinOptions.moduleKind = "commonjs"
}
Available values are: umd
(default), commonjs
, amd
, plain
.
This is different from adjusting
webpackTask.output.libraryTarget
. The library target changes the output generated by webpack (after your code has already been compiled).kotlinOptions.moduleKind
changes the output generated by the Kotlin compiler.
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)
Applying @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 compile-time error:
@file:JsModule("extModule")
package ext.jspackage.name
external fun foo()
fun bar() = "!" + foo() + "!" // error here
Importing 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 our 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. 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 kotlin
package.