Augmentations en Dart: qué cambia ahora que los macros están cancelados
Si seguías el roadmap de Dart esperando los macros para eliminar el boilerplate y despedirte de build_runner, hay una noticia que asimilar: los macros están cancelados. El equipo de Dart detuvo el trabajo en enero de 2025 porque cada obstáculo técnico que resolvían destapaba otro nuevo, y el coste en compilación incremental y hot reload no compensaba. En su lugar llega una pieza más modesta pero real: las augmentations.
Respuesta directa: las augmentations permiten partir la declaración de una clase, función o variable en varios fragmentos —incluso en archivos distintos— usando la palabra clave augment. No son un sistema de metaprogramación como iban a ser los macros: no introspeccionan tu código ni generan lógica por sí solas. Son el mecanismo sobre el que se apoya la generación de código para inyectar lo que genera sin sobrescribir tu fuente. build_runner no desaparece; mejora.
Este post explica qué son exactamente, qué problema resuelven, qué no resuelven, y cómo deberías planificar tu stack de generación de código en 2026.
Qué pasó con los macros (y por qué importa)
Los macros prometían metaprogramación en tiempo de compilación: escribir código Dart que, durante la compilación, lee la estructura de tus clases y genera nuevo código (serialización JSON, copyWith, ==, data classes…) sin ficheros .g.dart ni build_runner.
El problema fue la introspección semántica. Para que un macro supiera, por ejemplo, los tipos de todos los campos de una clase, el compilador tenía que resolver semántica de forma parcial durante la edición. Eso regresaba tanto el autocompletado como la compilación incremental, y la compilación incremental es exactamente lo que mantiene el hot reload rápido. El equipo concluyó que estaban demasiado lejos de un feature estable y pararon.
La lección para un equipo técnico: no construyas tu arquitectura sobre features experimentales de un roadmap. Los macros llevaban años en conversación y nunca llegaron. Las decisiones de stack se toman sobre lo que existe hoy.
Qué son las augmentations, con precisión
Una augmentation es una declaración que añade a una declaración existente en lugar de reemplazarla. Se marca con augment y el compilador funde todas las partes en una sola entidad.
// user.dart — lo que escribes tú
class User {
final String name;
final String email;
}
// user.g.dart — lo que genera la herramienta
augment class User {
Map<String, dynamic> toJson() => {
'name': name,
'email': email,
};
}
En lugar de generar una extension o una clase parcial con convenciones frágiles, la herramienta genera un augment class User que se integra en la clase original como si lo hubieras escrito tú. El resultado es más limpio: los miembros generados son de primera clase (pueden ser privados, acceder a estado interno, formar parte del constructor).
Puntos clave:
- No hay introspección en runtime ni en tu código. Las augmentations no leen tu clase por sí solas; una herramienta externa —normalmente vía
build_runner— produce el fichero de augmentation. - Se apoyan en la generación de código existente, no la sustituyen. Cambian cómo se inyecta el código generado, no quién lo genera.
- Encajan de forma natural con los primary constructors, otra mejora de Dart que reduce boilerplate en la declaración de clases. Si aún no los has visto, los cubrimos en detalle en nuestro artículo sobre primary constructors.
Cuándo NO esperes que las augmentations te salven
Es fácil leer "adiós al boilerplate" y sobredimensionar el impacto. Seamos honestos sobre los límites:
- No eliminan
build_runner. Si usasfreezed,json_serializableoriverpod_generator, seguirás lanzando el generador. La promesa "cero build step" era de los macros, y esa promesa ya no existe. - No aceleran mágicamente tu build. Las mejoras de rendimiento de
build_runnerque el equipo de Dart ha priorizado (con speedups notables en algunos escenarios) son un esfuerzo aparte de las augmentations. - No son metaprogramación. No puedes escribir lógica arbitraria que se ejecute en compilación. Si tu caso de uso real necesitaba eso, la respuesta hoy es: sigue con generación de código basada en
source_gen.
Si tu equipo estaba posponiendo decisiones "hasta que lleguen los macros", ese bloqueo debe levantarse. La ruta soportada en 2026 es generación de código pragmática (build_runner + augmentations + primary constructors), no metaprogramación.
Tabla: macros vs augmentations vs build_runner
| Aspecto | Macros (cancelado) | Augmentations | build_runner + source_gen |
|---|---|---|---|
| Estado | Cancelado (ene 2025) | En desarrollo, se enviará de forma independiente | Estable y en producción |
| Introspección de tu código | Sí (semántica en compilación) | No | Sí (analizador, en build step) |
| Requiere paso de build | No (era la promesa) | Sí (lo genera una herramienta) | Sí |
| Impacto en hot reload | Regresión (causa de la cancelación) | Mínimo | Ninguno en runtime |
| Recomendación 2026 | No planificar sobre ello | Adoptar cuando estabilice | Base actual del stack |
Qué hacer hoy con tu proyecto Flutter
Recomendaciones concretas para un equipo que mantiene apps Flutter en producción:
- Mantén tu pipeline de
build_runnery actualiza a las versiones que incorporan las mejoras de rendimiento; en muchos proyectos el cuello de botella real es la configuración, no la herramienta. - Adopta primary constructors para reducir boilerplate de declaración de forma soportada y estable.
- Sigue las augmentations en las notas de release de Dart, pero trátalas como una mejora incremental de la generación de código, no como un cambio de paradigma.
- Revisa tu serialización. El motivo original de los macros era la serialización de datos; el equipo de Dart lo señaló como su issue más solicitado. Si ese dolor es tuyo, evalúa
freezed 3.xy su modo mixto antes de esperar a un feature futuro.
Conclusión
La cancelación de los macros no es un fracaso: es el tipo de decisión honesta de ingeniería que preferimos: no enviar algo que degrada la experiencia de desarrollo para cumplir una promesa. Las augmentations son la parte del trabajo que sí sobrevive, y son útiles —hacen que el código generado se integre limpiamente— pero no reescriben las reglas. En 2026 el stack de generación de código en Dart es más pragmático y menos mágico de lo que se anunció, y eso es bueno para quien tiene que mantener el proyecto dentro de tres años.
En Dribba somos Partner oficial de Flutter en el directorio de Google y trabajamos con estas decisiones a diario en proyectos de producción. Si tu equipo necesita ordenar su arquitectura Flutter o reforzar el equipo con perfiles senior, hablemos sobre staff augmentation en Flutter.
