El ecosistema web: npm, tipos, empaquetado y entornos

Un backend de compilación se juzga por el código que emite; un objetivo de plataforma se juzga por lo bien que se integra en la vida cotidiana de esa plataforma, y son dos exámenes distintos. Kotlin/JS aprobó el primero hace años y el segundo le costó bastante más, porque el ecosistema de JavaScript no es una biblioteca estándar sino un organismo con gestor de paquetes propio, varios formatos de módulo históricamente incompatibles, un sistema de tipos paralelo que vive en ficheros aparte y dos entornos de ejecución que comparten el lenguaje pero casi ninguna interfaz. La respuesta de Kotlin fue no competir con nada de eso, sino integrarse: el complemento de Gradle sabe hablar con npm, el compilador entiende los formatos de módulo, el empaquetador del ecosistema se invoca desde la construcción y las definiciones de tipos se generan para que el otro lado no note que el módulo vino de otro lenguaje. Entender esa integración es lo que separa un experimento que funciona en la máquina propia de un artefacto que un equipo de web puede consumir sin saber que existe Kotlin.

Dependencias de npm desde Gradle

El complemento de Kotlin unifica dos mundos de gestión de dependencias bajo un único guion de construcción. Las bibliotecas de Kotlin y las multiplataforma se declaran como siempre; los paquetes de npm se declaran con una función dedicada, y el complemento se encarga de descargarlos e instalarlos usando la maquinaria del ecosistema.

kotlin {
    js {
        browser()
        binaries.executable()
    }
    sourceSets["jsMain"].dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
        implementation(npm("date-fns", "4.1.0"))
    }
}

De esa instalación surge un fichero de bloqueo que fija las versiones exactas del árbol de dependencias transitivas. Es un artefacto de construcción tan importante como cualquier otro y debe versionarse en el repositorio: sin él, dos máquinas que construyan el mismo proyecto en semanas distintas pueden acabar con árboles de npm diferentes, y la reproducibilidad se pierde justo en la parte del sistema que menos garantías ofrece.

Describir el paquete en Kotlin

Un paquete instalado no es todavía utilizable: hace falta contarle al compilador qué hay dentro. Eso se hace con declaraciones external anotadas para indicar de qué módulo proceden.

@JsModule("date-fns")
external object DateFns {
    fun formatDistance(fecha: Date, base: Date): String
}

// Una funcion exportada por defecto, en su propio fichero
@file:JsModule("is-sorted")

external fun <T> sorted(a: Array<T>): Boolean

Aquí aparece la pregunta que todo el mundo hace: si el paquete ya trae definiciones de TypeScript, por qué hay que reescribirlas. La respuesta honesta es que la generación automática de declaraciones a partir de esos ficheros fue una vía experimental que no llegó a consolidarse, y que hoy el camino recomendado es escribir a mano la parte de la API que realmente se usa. Esto suena a trabajo y en la práctica suele ser una ventaja: una declaración escrita a mano cubre las cinco funciones que el proyecto invoca en lugar de las trescientas del paquete, se lee, se revisa y sirve además como frontera documentada.

En sentido contrario el flujo sí está automatizado. El compilador genera un fichero de definiciones de tipos a partir de todo lo marcado con @JsExport, tanto en el objetivo de JavaScript como en el de WebAssembly, donde se habilita con una función explícita en el bloque de configuración.

Empaquetar

La salida del compilador son módulos de JavaScript, no una aplicación lista para servir. El paso que falta lo hace un empaquetador del propio ecosistema, que el complemento de Gradle invoca por debajo: resuelve las importaciones, une el código de Kotlin con el de npm, aplica la minificación y produce los ficheros que se publican. En el objetivo de navegador viene además un servidor de desarrollo con recarga, que combinado con la construcción continua de Gradle da el ciclo corto al que uno está acostumbrado en la web.

kotlin {
    js {
        browser {
            commonWebpackConfig {
                outputFileName = "app.js"
            }
            testTask {
                useKarma { useChromeHeadless() }
            }
        }
    }
}

Para el objetivo de Node el empaquetado suele sobrar, porque allí el sistema de módulos ya resuelve las importaciones en tiempo de carga y no hay que enviar nada por la red.

kotlin {
    js {
        nodejs()
        binaries.executable()
    }
}

El formato de módulo elegido gobierna cómo se consume el resultado, y aquí hay una asimetría que conviene tener presente al planificar una migración: Kotlin/JS admite tanto módulos ES como los formatos heredados, mientras que Kotlin/Wasm solo produce módulos ES y expone lo exportado como propiedades del objeto por defecto del módulo generado. Un proyecto que hoy publique en un formato antiguo tendrá que modernizar su forma de publicación antes de plantearse el otro backend.

flowchart LR
A[Fuentes Kotlin] --> B[Compilador]
C[Paquetes npm] --> D[Fichero de bloqueo]
B --> E[Modulos JavaScript]
D --> E
E --> F[Empaquetador]
F --> G[Artefacto servible]
B --> H[Definiciones de tipos]
H --> I[Consumidores en TypeScript]

Navegador y Node no son el mismo entorno

Comparten el lenguaje y casi nada más. El navegador aporta el modelo de documento, el almacenamiento local, la interfaz de red del cliente y un modelo de seguridad de origen; Node aporta sistema de ficheros, procesos, red de servidor y un conjunto de módulos propios. Ningún objeto global del uno existe en el otro, así que el código que toca el documento no puede compartirse con el que lee un fichero, por mucho que ambos compilen al mismo lenguaje.

La consecuencia práctica es de arquitectura y no de configuración. La lógica de negocio pura se escribe en el conjunto de fuentes común, sin tocar ninguna API de entorno; el acceso al documento y el acceso al sistema de ficheros se aíslan detrás de una interfaz declarada en común e implementada en cada lado. Es exactamente la disciplina de la multiplataforma aplicada a dos entornos que engañan porque hablan el mismo idioma.

// commonMain: la logica no sabe donde vive
interface AlmacenDePreferencias {
    fun leer(clave: String): String?
    fun escribir(clave: String, valor: String)
}

// El navegador lo resuelve con almacenamiento local;
// Node lo resuelve con un fichero. La logica no cambia.
class Ajustes(private val almacen: AlmacenDePreferencias) {
    var idioma: String
        get() = almacen.leer("idioma") ?: "es"
        set(v) = almacen.escribir("idioma", v)
}

Hay además un matiz de seguridad que separa los dos entornos y que no tiene equivalente en la JVM: el navegador impone una política de origen que gobierna qué peticiones puede hacer el código y qué respuestas puede leer. Un módulo que funciona sin problemas bajo Node porque allí no existe esa política puede fallar de forma desconcertante en el navegador, y el error no estará en Kotlin sino en la configuración del servidor que responde.

Hay además una diferencia de pruebas que sorprende a quien llega desde la JVM: las pruebas del objetivo de navegador se ejecutan en un navegador real sin interfaz gráfica, lanzado por la construcción, con todo lo que eso implica en tiempo de arranque y en dependencias de la máquina de integración continua. Las de Node arrancan en un instante. Repartir bien qué se prueba en cada sitio es una decisión de coste, no de cobertura.