Automatic generation of external declarations with Dukat

Dukat is still experimental. If you encounter any problems, please report them in Dukat's issue tracker.

Dukat is a tool currently in development which allows the automatic conversion of TypeScript declaration files (.d.ts) into Kotlin external declarations. This aims to makes it more comfortable to use libraries from the JavaScript ecosystem in a type-safe manner in Kotlin, reducing the need for manually writing external declarations and wrappers for JS libraries.

The Kotlin/JS Gradle plugin provides an integration with Dukat. When enabled, type-safe Kotlin external declarations are automatically generated for npm dependencies that provide TypeScript definitions. You have two different ways of selecting if and when Dukat should generate declarations: at build time, and manually via a Gradle task.

Generating external declarations at build time

The npm dependency function takes a third parameter after the package name and version: generateExternals. This allows you to control whether Dukat should generate declarations for a specific dependency:

dependencies {
    implementation(npm('decamelize', '4.0.0', true))
}

dependencies {
    implementation(npm("decamelize", "4.0.0", generateExternals = true))
}

If the repository of the dependency you wish to use does not provide TypeScript definitions, you can also use types provided via the DefinitelyTyped repository. In this case, make sure you add npm dependencies for both your-package and @types/your-package (with generateExternals = true).

You can use the flag kotlin.js.generate.externals in your gradle.properties file to set the generator's behavior for all npm dependencies simultaneously. As usual, individual explicit settings take precedence over this general flag.

Manually generating external declarations via Gradle task

If you want to have full control over the declarations generated by Dukat, want to apply manual adjustments, or if you're running into trouble with the auto-generated externals, you can also trigger the creation of the declarations for all your npm dependencies manually via the Gradle task generateExternals. This will generate declarations in a directory titled externals in your project root. Here, you can review the generated code and copy any parts you would like to use to your source directories.

It is recommended to only provide external declarations manually in your source folder or enabling the generation of external declarations at build time for any single dependency. Doing both can result in resolution issues.