Installation & Usage

ktox-js provides a Gradle plugin to integrate Kotlin-to-JS transpilation into your build process.

Gradle Setup

Standard JavaScript (ESModules)

To target modern web browsers or Node.js environments using ES6 modules, apply the com.isycat.ktox.js plugin:

plugins {
    id("com.isycat.ktox.js") version "0.1.0"
}

kotlinToJs {
    // Optional: package prefix to strip from output paths and import statements.
    // When set, 'com.example.myapp.MyClass' becomes just 'MyClass' in JS.
    rootNamespace.set("com.example")

    // Optional: import prefixes that should NOT generate an import statement.
    // Useful for library globals already available at runtime.
    skipImportPackages.add("com.example.natives")

    // Optional: directory where generated .js files are written.
    // Defaults to <buildDir>/generated/js
    outputDirectory.set(layout.buildDirectory.dir("custom-js-out"))
}

Dota 2 Panorama / V8

For environments where scripts are loaded inline (like Dota 2 Panorama) and do not support a module system, use the v8 variant. This variant suppresses import and export statements:

plugins {
    id("com.isycat.ktox.js.v8") version "0.1.0"
}

kotlinToV8Js {
    // Same options as above:
    rootNamespace.set("com.example")
    skipImportPackages.add("com.example.panorama.api")
}

Programmatic Usage

You can also use the KotlinToJsTranspiler directly in your own tools. It requires access to the project's source files to build a symbol index for cross-file resolution:

val sourceFiles = listOf(File("src/main/kotlin/MyScript.kt"), File("src/main/kotlin/Utils.kt"))
val transpiler = KotlinToJsTranspiler(useV8 = true)

val js = transpiler.transpile(
    sourceFile = sourceFiles[0],
    allSourceFiles = sourceFiles,
    rootNamespace = "com.example",
    skipImportPackages = setOf("com.example.natives")
)

println(js)

Configuration Options

Option	Description	Default
rootNamespace	Root package prefix to strip from output file paths and generated import paths.	""
skipImportPackages	Set of FQN prefixes for which no import statement should be generated.	setOf("kotlin.*")
outputDirectory	Directory where the generated .js files will be written.	build/generated/js[-v8]
failOnKotlinErrors	Whether to wait for compileKotlin and fail if there are errors.	true

Gradle Tasks

Task	Description	Group
transpileKotlinToJs / transpileKotlinToV8Js	Transpiles Kotlin sources to JavaScript. Wired into assemble.	build
checkJsOutput	Syntax-checks every emitted .js with node --check (skips when node is not on the PATH). Wired into check.	verification

Targets

ES6 Modules (Default)

By default, com.isycat.ktox.js generates ES6 modules with import and export statements. This is suitable for modern web development and Node.js.

V8 / Panorama (com.isycat.ktox.js.v8)

When targeting Dota 2 Panorama or other embedded V8 environments where scripts are loaded inline: * No import or require statements are emitted. * Kotlin package declarations are emitted as comments. * Classes and top-level functions are emitted as global-ready definitions.