Модули JavaScript

Вы можете компилировать проекты Kotlin в модули JavaScript для различных популярных систем модулей. В настоящее время поддерживаются следующие конфигурации модулей JavaScript:

Модули ES — стандартный способ объявить модуль в JavaScript (с синтаксисом JavaScript import/export). Используется по умолчанию, если для target задано значение es2015.
Унифицированные определения модулей (UMD), совместимые как с AMD, так и с CommonJS. Модули UMD также можно выполнять без импорта или при отсутствии системы модулей. Это вариант по умолчанию для целевых платформ browser и nodejs.
Асинхронные определения модулей (AMD), которые используются, в частности, библиотекой RequireJS.
CommonJS, широко используемый в Node.js/npm (функция require и объект module.exports).
Обычный. Не компилировать для какой-либо системы модулей. Доступ к модулю можно получить по его имени в глобальной области видимости.

Целевые платформы для браузера

Если вы собираетесь запускать код в браузере и хотите использовать систему модулей, отличную от UMD, можно указать нужный тип модуля в блоке конфигурации webpackTask. Например, чтобы переключиться на CommonJS, используйте:

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

Webpack поддерживает два варианта CommonJS — commonjs и commonjs2, которые влияют на способ предоставления объявлений. В большинстве случаев вам, вероятно, понадобится commonjs2, добавляющий синтаксис module.exports в сгенерированную библиотеку. Кроме того, можно выбрать параметр commonjs, который строго соответствует спецификации CommonJS. Подробнее о различиях между commonjs и commonjs2 см. в репозитории Webpack.

Библиотеки JavaScript и файлы Node.js

Если вы создаёте библиотеку для использования в средах JavaScript или Node.js и хотите использовать другую систему модулей, инструкции немного отличаются.

Выбор целевой системы модулей

Чтобы выбрать целевую систему модулей, задайте параметр компилятора moduleKind в скрипте сборки Gradle:

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

Доступны следующие значения: umd (по умолчанию), es, commonjs, amd, plain.

В Kotlin DSL для Gradle также есть сокращённый способ задать виды модулей CommonJS и ESM:

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

Аннотация @JsModule

Чтобы сообщить Kotlin, что класс, пакет, функция или свойство external является модулем JavaScript, можно использовать аннотацию @JsModule. Предположим, у вас есть следующий модуль CommonJS с именем «hello»:

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

В Kotlin его следует объявить так:

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

Применение @JsModule к пакетам

Некоторые библиотеки JavaScript экспортируют пакеты (пространства имён), а не функции и классы. В терминах JavaScript это объект, содержащий элементы — классы, функции и свойства. Импортировать такие пакеты как объекты Kotlin часто неудобно. Компилятор может сопоставлять импортированные пакеты JavaScript с пакетами Kotlin с помощью следующей записи:

@file:JsModule("extModule")

package ext.jspackage.name

external fun foo()

external class C

Соответствующий модуль JavaScript объявляется так:

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

Файлы, помеченные аннотацией @file:JsModule, не могут объявлять не внешние элементы. Пример ниже приводит к ошибке компиляции:

@file:JsModule("extModule")

package ext.jspackage.name

external fun foo()

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

Импорт вложенных иерархий пакетов

В предыдущем примере модуль JavaScript экспортирует один пакет. Однако некоторые библиотеки JavaScript экспортируют из одного модуля несколько пакетов. Kotlin также поддерживает этот случай, но для каждого импортируемого пакета необходимо объявить отдельный файл .kt.

Например, немного усложним предыдущий пример:

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

Чтобы импортировать этот модуль в Kotlin, нужно написать два исходных файла Kotlin:

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

package extlib.pkg1

external fun foo()

external fun bar()

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

package extlib.pkg2

external fun baz()

Аннотация @JsNonModule

Если объявление помечено как @JsModule, его нельзя использовать в коде Kotlin, если он не компилируется в модуль JavaScript. Обычно разработчики распространяют библиотеки как модули JavaScript и как загружаемые файлы .js, которые можно скопировать в статические ресурсы проекта и подключить с помощью тега <script>. Чтобы сообщить Kotlin, что объявление @JsModule можно использовать в среде без модулей, добавьте аннотацию @JsNonModule. Например, рассмотрим следующий код JavaScript:

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

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

В Kotlin его можно описать следующим образом:

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

Система модулей стандартной библиотеки Kotlin

Kotlin распространяется со стандартной библиотекой Kotlin/JS в виде одного файла, который сам скомпилирован как модуль UMD, поэтому его можно использовать с любой из описанных выше систем модулей. В большинстве случаев использования Kotlin/JS рекомендуется добавить зависимость Gradle от kotlin-stdlib-js, которая также доступна в NPM как пакет kotlin.

12 августа 2026 г.

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/js-modules.html