Skip to content

6. Capítulo 5 - Portabilidad de la aplicación Flutter a móvil, escritorio y web

6.1. Un único código fuente, múltiples destinos de compilación

Este es el núcleo de este capítulo y la razón de ser de esta variante del curso: NINGUNA línea del Capítulo 4 ([lib/], [pubspec.yaml], [assets/]) cambia, sea cual sea el destino seleccionado. “Portar” la aplicación aquí consiste simplemente en elegir un COMANDO DE COMPILACIÓN diferente ([flutter run -d <target>] o [flutter build <target>]), sin tener que escribir, duplicar ni adaptar ningún widget. Esto es muy distinto de lo que habría requerido un port con las herramientas tratadas en el resto de este curso: un cliente [Vue.js]/[React]/[Angular] se ejecuta de forma NATIVA solo en un navegador; portarlo a móvil requiere una herramienta de TERCEROS ([Cordova]/[Capacitor], no utilizadas en este curso) que lo empaqueta en un contenedor nativo que contiene, en realidad, un navegador integrado (un [WebView]): el código permanece sin cambios, pero SIGUE sin ser un ejecutable nativo, a diferencia de lo que [Flutter] produce aquí para móvil y escritorio (véase el Capítulo 3, “Lo que Flutter no es”).

Los seis destinos ([Android], [iOS], [macOS], [Windows], [Linux], [web]) están habilitados POR DEFECTO en cualquier proyecto creado con [flutter create] desde [Flutter 3] (véase el Capítulo 1); no se requiere ninguna configuración en el proyecto para agregar uno. Las únicas diferencias entre un destino y otro son: las herramientas de compilación nativas instaladas en la máquina de desarrollo ([Xcode], [Visual Studio], [GTK]...), el comando exacto que se ejecuta y, solo para móvil, un detalle de configuración de red que se describe más adelante en este capítulo.

6.2. Destino web

El destino ya utilizado en el Capítulo 2 ([flutter run -d chrome]). Bastan dos comandos:

flutter run -d chrome              # desarrollo, con recarga en caliente
flutter build web                  # compilación de producción, en build/web/

[flutter build web] genera una carpeta independiente [build/web/] ([index.html], [JavaScript], o [WebAssembly] compilado, recursos) para desplegar en CUALQUIER servidor web estático ([Nginx], [Apache], un simple [npx serve]....), exactamente como la carpeta [dist/] generada por [npm run build] del lado de [Vue.js]/[Vite]. Esta compilación sigue siendo un archivo [JavaScript] servido a un navegador: por lo tanto, sigue dependiendo de un servidor [NestJS] ALCANZABLE desde ese navegador, y por ende de [app.enableCors()] (véase [src/main.ts] en el servidor), que ya está activo, sin necesidad de cambios en el servidor para este destino.

Un punto a tener en cuenta específico de este destino: el campo “URL del servidor” de la pantalla de inicio de sesión (véase [_ServerUrlField] en [lib/app.dart], Capítulo 4) debe apuntar entonces a una dirección ALCANZABLE desde el navegador que ejecuta la aplicación; [http://localhost:8080] es aceptable siempre que el servidor [NestJS] se ejecute en la MISMA máquina que el navegador.

6.3. Destino de escritorio

Tres sistemas operativos, tres conjuntos de herramientas nativas requeridas (véase el Capítulo 1), pero comandos [flutter] idénticos en su forma:

1
2
3
4
5
6
7
flutter run -d macos               # macOS: requiere Xcode
flutter run -d windows              # Windows: requiere Visual Studio (C++ Desktop)
flutter run -d linux                # Linux: requiere los paquetes de desarrollo de GTK

flutter build macos                 # compilación de producción
flutter build windows
flutter build linux

Cada comando [flutter build <target>] produce un ejecutable nativo AUTÓNOMO ([.app] en macOS, [.exe] + sus bibliotecas en Windows, un binario [ELF] en Linux), en [build/<target>/]: un ejecutable que, a diferencia de la compilación web, no se ejecuta en NINGÚN navegador ni en NINGÚN [WebView]: es código nativo que se ejecuta directamente sobre el sistema operativo, con su propia ventana y barra de título, gestionado por [Flutter] mismo.

Este destino no requiere NINGUNA configuración de red especial: una aplicación de escritorio se ejecuta en la misma máquina que el usuario y accede a [http://localhost:8080] exactamente como lo haría cualquier otro programa instalado en esa máquina (el campo “URL del servidor” de la pantalla de inicio de sesión permite, como en los demás destinos, apuntar a un servidor remoto si es necesario).

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices    
Found 4 connected devices:
  sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
  Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
  10.0.26200.9457]
  Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
  Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

Run "flutter emulators" to list and start any available device emulators.

If you expected another device to be detected, please run "flutter doctor" to diagnose potential issues. You
may also try increasing the time to wait for connected devices with the "--device-timeout" flag. Visit
https://flutter.dev/setup/ for troubleshooting tips.
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d windows

Esto produce el siguiente resultado:

Image

La pantalla anterior no proviene de un navegador sino de una aplicación de Windows. Para que esto funcione, deben estar disponibles ciertas herramientas:

1
2
3
4
[√] Visual Studio - develop Windows apps (Visual Studio Build Tools 2026 18.9.0) [221ms]
    • Visual Studio at C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools
    • Visual Studio Build Tools 2026 version 18.9.12105.275
    • Windows 10 SDK version 10.0.26100.0

Para obtener un panorama claro de lo que falta en su proyecto Flutter, escriba el siguiente comando:

flutter doctor -v

6.4. Emuladores de destino

La aplicación Flutter se probó en un emulador de Android:

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices       
Found 4 connected devices:
  sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
  Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
  10.0.26200.9457]
  Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
  Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

...
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d emulator-554

El resultado en el emulador:

Image

  • Observe la URL en [1];

Al iniciar sesión con admin / admin se obtiene el siguiente resultado:

Image

Complete el formulario y luego envíelo:

Image

Arriba se ve el horario que reservamos con la aplicación web.

6.5. Destino móvil

Nota: El revisor no ha probado esta sección.

Esta es el área que requiere mayor atención, debido a un detalle específico de la red del emulador o simulador.

1
2
3
4
5
6
7
8
9
flutter emulators                   # lista los emuladores de Android configurados
flutter emulators --launch <id>     # inicia un emulador de Android
open -a Simulator                   # inicia un simulador de iOS (solo macOS)

flutter run -d <emulator-or-device-id>

flutter build apk                   # compilación de Android (.apk), o bien:
flutter build appbundle             # compilación de Android para Play Store (.aab)
flutter build ios                   # compilación de iOS: requiere macOS + Xcode + una cuenta de desarrollador de Apple para un dispositivo físico

6.5.1. La trampa de red específica de los dispositivos móviles: localhost ya no hace referencia a la PC de desarrollo

Este es EL detalle que hay que conocer para este destino, ajeno a [Flutter] en sí: [localhost] (o [127.0.0.1]), en el campo “URL del servidor” de la pantalla de inicio de sesión, hace referencia SIEMPRE a la máquina que ejecuta el código, y un emulador o simulador móvil es una máquina VIRTUAL DISTINTA de la máquina de desarrollo donde se ejecuta el servidor ([NestJS]), aunque ambas parezcan “estar en la misma computadora”.

  • [Android] Emulador (creado por [Android Studio]): use [http://10.0.2.2:8080], una dirección especial propia del emulador oficial de [Android], que redirige automáticamente a [localhost] de la máquina anfitriona (la PC de desarrollo).
  • [iOS] Simulador (solo macOS): [http://localhost:8080] funciona directamente, ya que el simulador de [iOS] comparte la red de la máquina anfitriona (a diferencia del emulador de [Android]).
  • Dispositivo físico ([Android] o [iOS], conectado a la misma red Wi-Fi que la PC de desarrollo): use la dirección [IP] LOCAL de esta PC en esa red (por ejemplo, [http://192.168.1.42:8080]), nunca [localhost] ni [10.0.2.2], ya que en este caso ambas hacen referencia al propio dispositivo móvil.

6.5.2. Dos restricciones adicionales específicas del dispositivo móvil

  • [Android] (desde la API 28) bloquea de forma predeterminada todo el tráfico [HTTP] en TEXTO PLANO (no cifrado con [https://]); dado que el servidor de este curso escucha en [HTTP] en modo simple, una aplicación [Android] LISTA PARA PRODUCCIÓN debería declarar una excepción explícita ([android:usesCleartextTraffic="true"] en el manifiesto de [Android] generado, o una configuración de seguridad de red más granular), un ajuste de configuración nativo, en [android/], ajeno al código [Dart] presentado en este documento.
  • [iOS] aplica una política comparable, [App Transport Security] ([ATS]), que también bloquea el [HTTP] en texto plano de forma predeterminada; se declara una excepción equivalente en [ios/Runner/Info.plist] ([NSAppTransportSecurity], [NSAllowsArbitraryLoads] o, de forma más específica, una excepción dirigida únicamente al dominio del servidor de desarrollo).

Estos dos ajustes se aplican ÚNICAMENTE al desarrollo o la demostración con un servidor [HTTP] sin cifrar, como el que se utiliza en este curso; un despliegue real en producción expondría en cambio el propio servidor [NestJS] en [https://] (por ejemplo, detrás de un [reverse proxy] como [Nginx]), lo que haría innecesarias estas dos excepciones.

6.5.3. Una pantalla más estrecha: la trampa del diseño

Una última diferencia específica de los dispositivos móviles no tiene nada que ver con la red: un teléfono en orientación vertical mide solo unos 360 píxeles de ancho (en píxeles lógicos de [Flutter]), frente a varios cientos más en una ventana de navegador o de escritorio. Por lo tanto, una pantalla diseñada para un monitor grande puede volverse inutilizable en un teléfono: esto es lo que le ocurrió a la primera versión del cliente de este documento, probada en un emulador de [Android]. El selector de médico/día/botón ([doctor_day_picker.dart]) alineaba tres campos dentro de una sola [Row], y la barra de título ([app.dart]) mostraba todo a la vez: había que cambiar el emulador a modo horizontal para verlo todo. El Capítulo 4 muestra la corrección. De esto se derivan dos reglas:

  • Nunca suponga un ancho. Para elegir un diseño, verifique el ancho realmente disponible, ya sea en un lugar específico del árbol mediante [LayoutBuilder] ([constraints.maxWidth]), o para toda la pantalla con [MediaQuery.sizeOf(context).width]; luego elija [Row] (pantalla ancha) o [Column] (pantalla estrecha).
  • Pruebe pronto en una pantalla estrecha: use el emulador en modo vertical, o una ventana de [Chrome] que usted reduzca de ancho. En modo de depuración, [Flutter] indica que el contenido es demasiado ancho mediante una franja amarilla y negra con el texto “RIGHT OVERFLOWED BY … PIXELS” en la aplicación, así como un mensaje en la consola.

Esto no contradice la siguiente observación: el diseño se adapta según el TAMAÑO de la pantalla, nunca según la plataforma; no aparece ningún [if (kIsWeb)] . Reducir el ancho de una ventana de navegador o de escritorio activa exactamente el mismo diseño “estrecho” que un teléfono.

6.6. Tabla resumen

  • [web] — [flutter run -d chrome] / [flutter build web] — compilado a [JavaScript]/[WebAssembly], ejecutado por un navegador — URL del servidor: [localhost] (misma máquina).
  • [desktop] (macOS/Windows/Linux) — [flutter run -d <os>] / [flutter build <os>] — compilación nativa [AOT], ejecutable autónomo — URL del servidor: [localhost] (misma máquina).
  • [mobile] (emulador de Android) — [flutter run] — compilación nativa [AOT] — URL del servidor: [10.0.2.2] (dirección especial para el emulador).
  • [mobile] (simulador de iOS) — [flutter run] — compilación nativa [AOT] — URL del servidor: [localhost] (red compartida con el anfitrión).
  • [mobile] (dispositivo físico) — [flutter run] — compilación nativa [AOT] — URL del servidor: dirección [IP] local de la PC de desarrollo, + excepción [cleartext]/[ATS].

6.7. Lo que NO cambia en el código Dart

Para concluir este capítulo, conviene subrayar lo que NO fue necesario escribir ni adaptar para cubrir estas tres familias de destinos: ninguna condición [if (kIsWeb) { ... } else { ... }] aparece en el Capítulo 4, ningún archivo [_mobile.dart]/[_web.dart] separado, ni bibliotecas de abstracción adicionales. Las pocas decisiones ya tomadas en el Capítulo 4 bastan, por sí solas, para que este código sea portable entre las tres familias de destinos: [shared_preferences] (en lugar de [localStorage], que es específico del navegador) para la persistencia, [rootBundle.loadString(...)] (en lugar de un [fetch] a un servidor web) para los diccionarios de traducción integrados, y el paquete [http] (en lugar de una API específica del navegador) para la red. Esto es exactamente lo que prometía la introducción de este documento: [a single Flutter codebase is enough to build a mobile app, a desktop app and a web app].