1. O que é e por que usar

kotlinx-datetime é a biblioteca oficial da JetBrains para trabalhar com data e hora no ecossistema Kotlin. Sua principal característica é a multiplataforma: o mesmo código funciona em JVM, JS (navegador e Node.js), Native (iOS, macOS, Windows, Linux) e Wasm. Isso elimina a necessidade de escrever wrappers dependentes de plataforma ou usar bibliotecas diferentes para cada ambiente.

Por que usar? A biblioteca padrão do Kotlin/JVM utiliza java.time, que não está disponível em outras plataformas. Para Kotlin/Native e Kotlin/JS, era necessário usar APIs nativas (NSDate, Date) ou bibliotecas de terceiros. O kotlinx-datetime resolve esse problema oferecendo uma API unificada baseada na especificação ISO-8601. Ela inclui classes para representar instantes (Instant), datas sem hora (LocalDate), horas sem data (LocalTime), data com hora (LocalDateTime), fusos horários (TimeZone) e períodos (DateTimePeriod).

A biblioteca é ideal para projetos que usam Kotlin Multiplatform (KMP), aplicações server-side com Ktor, apps Android (como substituto do java.time) e até scripts e utilitários de console. Ela é leve, não possui dependências externas e é ativamente mantida pela comunidade.

2. Instalação

A biblioteca é distribuída via Maven Central. Para adicioná-la, inclua a dependência no arquivo build.gradle.kts (ou build.gradle). Abaixo está o código exato para Gradle Kotlin DSL.

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

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

    // Se você estiver usando um projeto multiplataforma, adicione em commonMain:
    // commonMain.dependencies {
    //     implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
    // }
}

Importante: A versão 0.6.1 é a última estável no momento da escrita deste artigo. Verifique a versão mais recente nos releases do GitHub. Para Gradle Groovy DSL, o comando é similar, mas sem aspas nas strings.

Se você usa Maven, adicione no pom.xml:

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

Para Gradle Kotlin DSL em um projeto multiplataforma (KMP), adicione no commonMain:

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

3. Início rápido

Exemplo mínimo funcional: obter o instante atual, formatá-lo e exibi-lo no console.

import kotlinx.datetime.*

fun main() {
    // Obtém o instante atual em UTC
    val now: Instant = Clock.System.now()
    println("Instante atual em UTC: $now")

    // Converte para data e hora local (usando o fuso horário do sistema)
    val localDateTime: LocalDateTime = now.toLocalDa