Optimización de binarios con Tree shaking en Dart

El Tree shaking es el proceso de optimización mediante el cual el compilador analiza el grafo de llamadas de tu aplicación para eliminar el “código muerto”. En términos simples: el compilador construye un mapa de todas las funciones y clases que son realmente alcanzables partiendo desde el punto de entrada, que es el main(). Cualquier código que no tenga un camino de ejecución que lo conecte con main() es descartado antes de generar el binario final.

Este proceso es fundamental en la compilación AOT (Ahead-of-Time) de Dart para CLI y servicios, y es el motor detrás de la minificación en dart compile js --minify. Si importas una librería que contiene 1,000 clases pero solo utilizas 10, el compilador es lo suficientemente inteligente como para no incluir las otras 990 en el binario resultante, reduciendo drásticamente el tamaño del archivo y el uso de memoria.

Sin embargo, el análisis de alcanzabilidad es estrictamente estático. Esto significa que el compilador solo puede eliminar lo que “ve” que no se usa. Esto presenta dos escenarios críticos:

1. Reflexión dinámica: El uso de dart:mirrors (disponible para entornos no-AOT) rompe el tree shaking. Como la reflexión permite invocar métodos mediante un String en tiempo de ejecución, el compilador no tiene forma de saber qué método vas a llamar, por lo que no puede asegurar que un método sea “inalcanzable” y, por seguridad, no lo elimina.
2. Entradas externas: Cuando escribes código que será llamado desde el lado nativo (vía FFI) o desde procesos fuera del runtime de Dart, el compilador no ve ninguna llamada hacia esa función desde main(). Para evitar que el tree shaker la elimine por considerarla inútil, debemos usar @pragma('vm:entry-point'), que marca explícitamente ese punto de entrada como vital.

Además, podemos forzar la eliminación de bloques enteros de código mediante constant folding. Si utilizas bool.fromEnvironment('FLAG') con una constante const, el compilador evalúa la condición durante la fase de compilación. Si la condición es falsa, el bloque if resultante se considera código muerto y se elimina por completo, evitando incluso la presencia de strings o constantes de depuración en el binario de producción.

Si fallas al gestionar estas optimizaciones, el resultado es doblemente peligroso: o tu binario crece innecesariamente al incluir dependencias pesadas que no usas, o tu aplicación fallará en producción con errores de tipo “method not found” porque el compilador eliminó una función que solo era alcanzable dinámicamente.

// Ejemplo de optimización de binario y Tree Shaking
import 'dart:io';

// Esta clase simula una librería externa masiva con múltiples utilidades.
class AnalyticsLibrary {
  void trackEvent(String name) => print('Evento registrado: $name');
  void heavyInitialization() => print('Operación pesada inalcanzable.');
  void internalCleanup() => print('Limpieza interna no utilizada.');
}

// El compilador AOT no puede ver llamadas que vienen de código nativo (FFI).
// Sin este pragma, el tree shaker eliminaría este método al notar que
// no hay ninguna llamada en el grafo que parta desde main().
@pragma('vm:entry-point')
void callbackFromNative() {
  print('Punto de entrada desde el lado nativo preservado.');
}

void main() {
  final analytics = AnalyticsLibrary();

  // Solo este método será incluido en el binario final.
  analytics.trackEvent('app_start');

  // Usamos bool.fromEnvironment con una constante.
  // El compilador realiza "constant folding": si se compila sin el flag,
  // el bloque 'if' y su contenido desaparecen por completo.
  // Ejecución: dart run --define=ENABLE_DEBUG=true
  // Producción: dart compile exe app.dart
  const bool isDebug = bool.fromEnvironment('ENABLE_DEBUG');

  if (isDebug) {
    print('Modo debug activo. Timestamp: ${DateTime.now()}');
    // Todo este bloque se elimina si isDebug es false en tiempo de compilación.
  }

  callbackFromNative();
  print('Ejecución finalizada.');
}

En el código anterior, el compilador realiza un análisis de alcanzabilidad sobre AnalyticsLibrary. Identifica que trackEvent es llamado desde main(), pero como heavyInitialization e internalCleanup no tienen ninguna referencia en el grafo de llamadas, sus instrucciones se eliminan del binario final.

Para callbackFromNative, el uso de @pragma('vm:entry-point') es la instrucción que impide que el optimizador la descarte. Sin esa anotación, el compilador la trataría como código muerto, provocando un error si intentas invocarla desde una librería nativa en producción.

Finalmente, la variable isDebug es la clave de la optimización de tamaño. Al usar const y bool.fromEnvironment, la condición if (isDebug) se resuelve en la fase de compilación. Si compilas para producción sin el flag --define=ENABLE_DEBUG=true, el compilador no solo ignora el bloque, sino que lo borra físicamente del bytecode/binario, asegurando que ni siquiera el texto de depuración llegue al usuario final.

El error frecuente

El error más sutil ocurre al intentar usar reflexión dinámica o métodos que parecen inalcanzables para resolver lógica en tiempo de ejecución en aplicaciones compiladas AOT.

// ESTO FALLARÁ EN PRODUCCIÓN (AOT)
void main() {
  var miObjeto = ClaseInutil();
  // Intentar acceder por reflexión es imposible en binarios AOT optimizados
  // porque el tree shaker ya eliminó la clase antes de que pudieras usarla.
  // Además, dart:mirrors no está disponible en AOT.
}

class ClaseInutil {
  void metodoSecreto() => print('Nunca verás esto en AOT');
}

Si confías en que una clase o método estará disponible basándote en su presencia en el código fuente sin haber establecido un camino de llamada estático o un @pragma, el optimizador hará su trabajo correctamente y “limpiará” tu aplicación, rompiendo la lógica que dependía de esa “presencia invisible”.

N° 104