Gradle KTS — qué es, Kotlin DSL para Gradle y su sintaxis

¿Qué es Gradle KTS?

Gradle KTS es un DSL de Kotlin (Domain Specific Language) que ofrece una alternativa a Groovy para escribir archivos de configuración de Gradle. En lugar de la sintaxis de Groovy, los desarrolladores usan Kotlin, un lenguaje fuertemente tipado que verifica la corrección de la configuración en tiempo de compilación. KTS se introdujo por primera vez en Gradle 5.0 en 2018 como una función experimental y alcanzó la estabilidad en Gradle 6.0.

El objetivo principal de KTS es eliminar las deficiencias de Groovy en los scripts de compilación. Groovy es un lenguaje de tipificación dinámica donde los errores de configuración solo aparecen en tiempo de ejecución al ejecutar una tarea. KTS permite detectar los mismos errores en la etapa de edición del código gracias a la tipificación estática de Kotlin. Además, KTS proporciona acceso a la API de Gradle con documentación completa de tipos, lo que simplifica significativamente el aprendizaje y uso de bloques de configuración complejos.

El ecosistema de KTS está soportado por todas las herramientas principales: Android Studio, IntelliJ IDEA, VS Code con el plugin de Kotlin y Gradle Build Tool. Todos los plugins modernos (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) proporcionan una API amigable con Kotlin con tipos explícitos, lo que convierte a KTS en la opción preferida para nuevos proyectos.

Cómo funciona Gradle KTS

Gradle KTS utiliza el compilador de Kotlin para procesar archivos .gradle.kts. Gradle reconoce la extensión y pasa los scripts al motor de scripting de Kotlin, que los compila en clases. Luego, Gradle ejecuta estas clases para construir el modelo del proyecto. La diferencia clave con Groovy: los scripts KTS se compilan previamente, no se interpretan dinámicamente, lo que permite detectar errores antes de que comience la ejecución de las tareas.

La arquitectura de KTS se basa en kotlin-scripting. Cada archivo .gradle.kts es un script de Kotlin con importaciones implícitas de la API de Gradle. El desarrollador puede usar cualquier construcción de Kotlin: funciones de extensión, lambdas, clases de datos e incluso declarar funciones auxiliares dentro del script de compilación. Gradle proporciona un conjunto de funciones de extensión para la configuración tipificada de bloques: dependencies, android, kotlin y otros.

plugins {
    id("com.android.application") version "8.4.0"
    kotlin("android") version "2.0.21"
}

android {
    namespace = "com.itsectr.app"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.itsectr.app"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0.0"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.core:core-ktx:1.13.1")
}

Conversión de tipos en KTS

Una de las diferencias clave entre KTS y Groovy es el manejo de tipos. En Groovy, todas las configuraciones aceptan Object, mientras que en KTS aceptan tipos específicos de Kotlin. Por ejemplo, compileSdk acepta Int, no una cadena. Esto elimina errores relacionados con tipos incorrectos: en Groovy, compileSdk 34 y compileSdk "34" funcionan igual, mientras que en KTS solo la primera variante es válida. Esta rigurosidad hace que la configuración sea más predecible y documentada.

Gradle KTS vs Groovy: comparación

Groovy fue el DSL original para Gradle y sigue siendo totalmente compatible. Sin embargo, KTS ofrece varias ventajas que lo convierten en la opción recomendada para proyectos nuevos. La tipificación estática, un mejor rendimiento de edición en el IDE y una sintaxis más estricta son las principales razones para cambiar a KTS. Al mismo tiempo, Groovy conserva su ventaja en concisión para configuraciones simples.

El rendimiento de compilación en KTS y Groovy es casi idéntico después de la compilación de scripts. Los scripts KTS tardan más en compilarse en la primera ejecución o después de limpiar el caché, pero las compilaciones posteriores funcionan a la misma velocidad que los scripts de Groovy. Gradle almacena en caché los scripts KTS compilados en el directorio de compilación, por lo que la recompilación solo ocurre cuando el script cambia.

La elección entre KTS y Groovy en 2026 es clara: para proyectos nuevos — KTS. Google, JetBrains y Gradle recomiendan KTS para todos los proyectos nuevos. Groovy sigue siendo relevante para el mantenimiento de proyectos heredados donde la migración no es práctica debido al volumen de configuración o a plugins específicos incompatibles con KTS.

Ejemplos de código: scripts de compilación en KTS

Veamos bloques de configuración típicos en KTS para Android, Kotlin Multiplatform y Compose Multiplatform. Un proyecto Android con KTS requiere especificación explícita de tipos en la configuración de buildTypes y productFlavors. El siguiente ejemplo muestra la configuración de una aplicación con dos sabores.

android {
    buildTypes {
        val release = getByName("release") {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        getByName("debug") {
            applicationIdSuffix = ".debug"
        }
    }

    flavorDimensions += "version"
    productFlavors {
        register("demo") {
            dimension = "version"
            versionNameSuffix = "-demo"
        }
        register("full") {
            dimension = "version"
        }
    }
}

Para Kotlin Multiplatform, KTS es obligatorio — Groovy no admite correctamente la configuración de módulos multiplataforma. La configuración del módulo KMM incluye la configuración de plataformas de destino y source sets. El siguiente ejemplo muestra la configuración del módulo compartido con iOS y Android.

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = "17"
            }
        }
    }

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
        androidMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
        }
    }
}

Funciones auxiliares y tareas personalizadas

KTS permite declarar funciones auxiliares de Kotlin dentro del script de compilación. Esto es especialmente útil para configuraciones repetitivas como signing configs o gestión de versiones. Gracias a la tipificación estática, estas funciones se pueden llamar con validación de parámetros en tiempo de compilación, eliminando errores en las configuraciones de firma antes de publicar en Google Play.

fun Project.configureSigning() {
    android {
        signingConfigs {
            register("release") {
                storeFile = file("release.keystore")
                storePassword = System.getenv("KEYSTORE_PASSWORD")
                keyAlias = System.getenv("KEY_ALIAS")
                keyPassword = System.getenv("KEY_PASSWORD")
            }
        }
    }
}

// Uso en build.gradle.kts
configureSigning()

Migración de Groovy a KTS

La migración de Groovy a KTS es un proceso que se puede realizar gradualmente. Gradle admite proyectos mixtos donde algunos módulos usan Groovy (build.gradle) y otros usan KTS (build.gradle.kts). El settings.gradle y el build.gradle raíz pueden migrarse primero ya que no dependen de los plugins de los módulos. Google recomienda comenzar la migración con settings.gradle.kts, luego el build.gradle.kts raíz, y solo después los módulos.

Los pasos principales de la migración incluyen: reemplazar la sintaxis de closures con lambdas, agregar signos = para asignaciones, reemplazar claves de cadena con constantes tipificadas y tipificación explícita de variables. Android Studio proporciona conversión automática de Groovy a KTS para bloques simples, pero las configuraciones complejas con closures anidadas requieren reescritura manual.

Los problemas típicos de migración incluyen llamadas implícitas a métodos de Groovy que no tienen equivalente en Kotlin, y plugins que no proporcionan una API amigable con Kotlin. Para el primer problema, Gradle proporciona compatibilidad a través de withGroovyBuilder, un mecanismo que permite llamar a métodos de Groovy desde KTS. Para el segundo, es necesario esperar una actualización del plugin o usarlo en un módulo de Groovy hasta la migración completa.

Gradle KTS para Kotlin Multiplatform

Kotlin Multiplatform es el proyecto principal donde KTS es un requisito obligatorio. El plugin kotlin multiplatform proporciona extensiones para configurar plataformas de destino, source sets y binarios de framework que solo están disponibles a través de Kotlin DSL. Groovy no admite correctamente la configuración multiplataforma, por lo que los proyectos KMM usan exclusivamente KTS.

La configuración de KMM en KTS incluye bloques no estándar: kotlin.target para especificar plataformas, kotlin.sourceSets para organizar el código común y específico de la plataforma, kotlin.cocoapods para la integración con CocoaPods y kotlin.jvmToolchain para la selección de JDK. Cada bloque tiene una API estrictamente tipificada con autocompletado en Android Studio, lo que es especialmente valioso para la configuración compleja de proyectos KMM con múltiples plataformas.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    cocoapods {
        summary = "Shared Kotlin module"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = false
        }
        pod("Alamofire") {
            version = "5.9"
        }
    }
}

Gracias a la tipificación estática de KTS, los desarrolladores de KMM obtienen autocompletado para source sets y dependencias, verificación de tipos de la configuración del framework y la capacidad de refactorizar nombres de plataformas. KTS también simplifica la depuración: los errores en la configuración de KMM aparecen como errores de compilación de Kotlin con mensajes claros, a diferencia de Groovy donde los errores podían estar ocultos hasta que se ejecutara una tarea de Gradle.