Version Catalogs en proyectos Android reales

El problema real

En proyectos Android medianos o grandes, las dependencias empiezan a repetirse. Un módulo declara Coroutines con una versión, otro con otra. Hilt aparece escrito distinto en tres lugares. Una librería se renombra, pero alguien se olvida de actualizar un módulo viejo. El proyecto sigue compilando, pero el mantenimiento se vuelve más costoso y menos predecible.

Ese es el problema que los Version Catalogs intentan resolver: no la arquitectura entera del build, sino el manejo centralizado de versiones y aliases de dependencias.

Qué son los Version Catalogs

Un Version Catalog es una forma de declarar versiones, librerías y plugins en un archivo central, normalmente gradle/libs.versions.toml, para luego referenciarlos desde los módulos con aliases tipados.

[versions]
kotlin = "2.1.0"
coroutines = "1.10.1"
retrofit = "2.11.0"

[libraries]
coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }

dependencies {
    implementation(libs.coroutines.core)
    implementation(libs.retrofit)
}

La ventaja visible es estética. La ventaja real es que movés el conocimiento de versiones a un punto común y reducís dispersión.

Qué resuelven

Resuelven sobre todo tres cosas.

• Consistencia: una misma librería no queda declarada con pequeñas variaciones en módulos distintos.
• Mantenibilidad: actualizar versiones deja de implicar recorrer medio proyecto manualmente.
• Legibilidad: un bloque de dependencias pasa a expresar intención más que detalle textual.

Qué no resuelven

No resuelven duplicación de lógica Gradle. No reemplazan convention plugins. No arreglan una mala modularización. Y no te dicen automáticamente qué dependencias debería tener cada módulo.

Eso es importante porque a veces se los presenta como una solución total de orden. No lo son. Son una pieza de orden, no el sistema completo.

Ejemplo concreto

Imaginá un proyecto con varios módulos Android. Sin catalog, cada módulo repite algo así:

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
}

Eso funciona, pero escala mal. Si cambiás una versión o querés un alias más descriptivo, hay que tocar varios lugares. Con catalog, el módulo deja de preocuparse por el string exacto:

dependencies {
    implementation(libs.coroutines.core)
    implementation(libs.retrofit)
}

La diferencia parece pequeña. En un módulo, lo es. En veinte módulos, no.

Cuándo convienen de verdad

Mi regla práctica sería esta:

• En proyectos medianos o grandes, casi siempre convienen.
• En proyectos con varios módulos, convienen todavía más.
• En un proyecto chico de un solo módulo, pueden ser útiles, pero no son urgentes.

Lo importante es no introducirlos como ritual, sino cuando ayudan a bajar ruido. Si el proyecto todavía es muy simple, no pasa nada por seguir un tiempo con declaraciones directas.

Errores comunes

• Crear aliases crípticos que nadie entiende.
• Meter absolutamente todo en el catalog sin criterio semántico.
• Usar catalogs para esconder decisiones de arquitectura que deberían verse en los módulos.
• Confundir “dependencias centralizadas” con “build bien diseñado”.

Un buen catalog debería hacer el proyecto más legible, no más mágico. Si leer un módulo requiere abrir cinco capas mentales para saber qué dependencia usa realmente, se perdió parte del beneficio.

Cierre

Los Version Catalogs son una mejora concreta para proyectos Android que empiezan a crecer: centralizan versiones, reducen duplicación y vuelven más limpio el uso de dependencias. Pero no reemplazan criterio de arquitectura, ni modularización, ni convention plugins. Funcionan mejor cuando se usan como herramienta de claridad, no como decoración moderna del build.