Catálogos de versiones: una única fuente de verdad para dependencias

Un catálogo de versiones es el mecanismo integrado de Gradle para declarar tus dependencias y sus versiones en un único archivo compartible, en lugar de dispersar cadenas de coordenadas y números de versión por cada build.gradle.kts del proyecto. El catálogo vive en gradle/libs.versions.toml (ojo: la carpeta gradle/, no la raíz) y Gradle lo descubre automáticamente: no se necesita ningún plugin ni configuración en settings.gradle.kts para el catálogo por defecto llamado libs. A partir de ese archivo Gradle genera un objeto de accesores con seguridad de tipos que referencias en tus scripts como libs.algo, lo que te da autocompletado en el IDE y un error en tiempo de compilación en cuanto un nombre está mal escrito o se elimina.

El archivo TOML se organiza en cuatro tablas. [versions] guarda cadenas de versión con nombre (o restricciones de versión enriquecidas) reutilizables, p. ej. kotlin = "2.1.0". [libraries] declara cada dependencia por su group, name y una referencia de versión hacia [versions] (o una versión en línea). [plugins] declara plugins de Gradle con su id y versión, que luego aplicas mediante el bloque plugins { }. [bundles] agrupa varios alias de librerías bajo un solo nombre para que puedas incorporar un conjunto relacionado — por ejemplo todo Ktor, o todas tus librerías de test — con una sola línea. Cada tabla es opcional, pero juntas describen toda tu superficie de dependencias en un solo lugar.

Los alias del catálogo usan guiones, puntos o guiones bajos como separadores, y Gradle los mapea a un accesor anidado y en camelCase. Un alias como androidx-core-ktx se convierte en libs.androidx.core.ktx, y kotlinx-coroutines-core en libs.kotlinx.coroutines.core. A las versiones se accede mediante libs.versions.<nombre> (por ejemplo libs.versions.kotlin.get() cuando necesitas la cadena cruda), a los bundles mediante libs.bundles.<nombre> y a los plugins mediante libs.plugins.<nombre>. Esta nomenclatura consistente y descubrible es gran parte de por qué los catálogos se sienten mucho mejores que las cadenas de coordenadas escritas a mano.

Centralizar las versiones importa cada vez más a medida que el proyecto crece. Cuando la misma librería aparece en varios módulos, un catálogo garantiza que todos usen exactamente la misma versión, eliminando los conflictos sutiles y difíciles de depurar que surgen cuando un módulo deriva silenciosamente hacia otra release. Actualizar se convierte en un cambio de una sola línea en libs.versions.toml que se propaga al instante a todas partes, y una única referencia de versión puede gobernar varios artefactos relacionados: sube la versión de kotlin una vez y el plugin del compilador, la librería estándar y la de reflexión se mueven juntas. El catálogo también se vuelve documentación viva: un revisor puede leer un solo archivo y saber exactamente de qué depende el proyecto.

Los catálogos brillan en builds multi-módulo porque el accesor libs generado está disponible automáticamente en el script de cada módulo e incluso en buildSrc / builds incluidos, así que no hay nada que configurar por módulo. Si mantienes varios repositorios, puedes publicar un catálogo como su propio artefacto e importarlo mediante un bloque versionCatalogs en settings.gradle.kts, compartiendo un único conjunto curado de versiones aprobadas en toda una organización. Las herramientas también entienden el formato: el tooling de 'versions' de Gradle y Dependabot/Renovate pueden leer y actualizar libs.versions.toml directamente.

Algunos consejos prácticos: mantén los nombres de alias descriptivos y estables, ya que forman parte de la superficie pública de tu build; prefiere referencias de versión sobre versiones en línea para que cada versión se defina una sola vez; usa bundles para grupos cohesivos pero no agrupes en exceso dependencias no relacionadas; y recuerda que el catálogo solo declara coordenadas — no pone nada en el classpath hasta que realmente referencias un alias en un bloque dependencies { } o plugins { }. Como los builds de Gradle se ejecutan fuera de este runner en el navegador, trata los fragmentos de abajo como la forma canónica y lista para copiar de un proyecto moderno Gradle 8 + Kotlin 2.x.

# gradle/libs.versions.toml — the single source of truth for versions

[versions]
kotlin = "2.1.0"
ktor = "3.0.3"
kotlinx-coroutines = "1.10.1"
junit = "5.11.4"

[libraries]
# group:name resolved with a version pulled from [versions]
ktor-server-core = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
ktor-server-netty = { module = "io.ktor:ktor-server-netty", version.ref = "ktor" }
kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[plugins]
# applied via the plugins { } block, not dependencies
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
ktor = { id = "io.ktor.plugin", version.ref = "ktor" }

[bundles]
# one alias that expands to several libraries at once
ktor-server = ["ktor-server-core", "ktor-server-netty"]

// build.gradle.kts — reference catalog entries type-safely as libs.xxx

plugins {
    // dashes/dots in aliases become nested accessors
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.ktor)
}

dependencies {
    // a bundle pulls in every library it groups
    implementation(libs.bundles.ktor.server)
    implementation(libs.kotlinx.coroutines.core)

    // a single library alias
    testImplementation(libs.junit.jupiter)
}

// need the raw version string? reach it through libs.versions
val kotlinVersion = libs.versions.kotlin.get()

// settings.gradle.kts — the default 'libs' catalog needs NO config here.
// You only add this block to import an EXTERNAL/published catalog.

dependencyResolutionManagement {
    versionCatalogs {
        create("shared") {
            // share one curated set of versions across repositories
            from("com.mycompany.platform:catalog:1.4.0")
        }
    }
}