1. ¿Qué es y por qué usarla?

kotlinx-datetime es la biblioteca oficial de JetBrains para manejar fechas y horas en el ecosistema Kotlin. Su principal ventaja es la multiplataforma: el mismo código funciona en JVM, JS (navegador y Node.js), Native (iOS, macOS, Windows, Linux) y Wasm. Esto evita tener que escribir envoltorios específicos para cada plataforma o usar bibliotecas distintas según el destino.

¿Por qué es necesaria? La biblioteca estándar de Kotlin/JVM usa java.time, que no está disponible en otras plataformas. Para Kotlin/Native y Kotlin/JS había que recurrir a APIs nativas (NSDate, Date) o a bibliotecas de terceros. kotlinx-datetime resuelve esto ofreciendo una API unificada basada en el estándar ISO-8601. Incluye clases para representar instantes de tiempo (Instant), fechas sin hora (LocalDate), horas sin fecha (LocalTime), fecha con hora (LocalDateTime), husos horarios (TimeZone) y periodos (DateTimePeriod).

Es ideal para proyectos con Kotlin Multiplatform (KMP), aplicaciones de servidor con Ktor, apps Android (como reemplazo de java.time) e incluso scripts y utilidades de consola. Es ligera, no tiene dependencias externas y cuenta con una comunidad activa que la mantiene.

2. Instalación

La biblioteca se distribuye a través de Maven Central. Para agregarla, solo tienes que añadir la dependencia en tu archivo build.gradle.kts (o build.gradle). Aquí tienes el código exacto para Gradle Kotlin DSL.

// build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    // Biblioteca principal
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

    // Si usas un proyecto multiplataforma, agrega en commonMain:
    // commonMain.dependencies {
    //     implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
    // }
}

Importante: La versión 0.6.1 es la última estable al momento de escribir esta guía. Verifica siempre la versión más reciente en los lanzamientos de GitHub. Para Gradle Groovy DSL el comando es similar, pero sin comillas en las cadenas.

Si usas Maven, agrega esto en tu pom.xml:

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime</artifactId>
    <version>0.6.1</version>
</dependency>

Para Gradle Kotlin DSL en un proyecto multiplataforma (KMP), agrega en commonMain:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
        }
    }
}

3. Inicio rápido

Un ejemplo mínimo funcional: obtener el instante actual, formatearlo y mostrarlo en consola.

import kotlinx.datetime.*

fun main() {
    // Obtenemos el instante actual en UTC
    val now: Instant = Clock.System.now()
    println("Instante actual en UTC: $now")

    // Convertimos a fecha y hora local (usando el huso horario del sistema)
    val localDateTime: LocalDateTime = now.toLocalDa