Convertir Next.js en APK no es exportar: así estoy construyendo next2apk
Cuando estudiaba desarrollo web, empezar un proyecto React significaba muchas veces escribir create-react-app y seguir adelante. Hoy el punto de partida suele ser bastante más completo: Next.js para la aplicación y Supabase para la base de datos, la autenticación, el almacenamiento y buena parte de la infraestructura.
Es una combinación razonable. También es una combinación que muchos LLMs recomiendan cuando les pides un SaaS, un dashboard o un MVP moderno. El problema aparece unas semanas después, cuando la aplicación web ya funciona y alguien pregunta: “¿Y si ahora la convertimos en una aplicación Android?”.
Ahí empieza otra historia. Y de ahí nace next2apk, un proyecto open source que estoy construyendo para automatizar, en la medida de lo posible, el camino entre una aplicación Next.js y un APK de Android.
El salto de Next.js a Android tiene más piezas de las que parece
Convertir una web app en Android no consiste simplemente en meter una URL dentro de una WebView. Hay que decidir cómo se entrega la aplicación, qué parte necesita un servidor y qué parte puede vivir dentro del paquete Android.
En el camino aparecen Capacitor, el Android SDK, Java, Gradle, el AndroidManifest, el identificador de aplicación, las variables de entorno, la firma del APK y, si queremos publicar en Google Play, el formato AAB. Capacitor aporta un runtime nativo para aplicaciones web y permite sincronizar el contenido generado con un proyecto Android, pero sigue apoyándose en las herramientas habituales del ecosistema Android. La documentación oficial exige, entre otros elementos, Android Studio y una instalación del SDK para desarrollar en Android. La guía de configuración de Capacitor lo deja bastante claro.
Además, no todas las aplicaciones Next.js son equivalentes. Una aplicación estática puede generar HTML, CSS y JavaScript y servirse desde cualquier servidor de archivos. Next.js documenta esta posibilidad mediante output: 'export', que produce una carpeta out durante el build. Pero las funciones que necesitan un servidor Node no desaparecen por empaquetar la interfaz en un APK. La documentación de Next.js sobre static exports enumera, precisamente, varias funciones que no son compatibles con una exportación estática, como API Routes, middleware, redirecciones o getServerSideProps.
La primera decisión: analizar antes de modificar
Por eso next2apk no empieza escribiendo archivos Android a ciegas. Primero analiza el proyecto. La herramienta detecta la versión de Next.js, el router utilizado, TypeScript, el gestor de paquetes, las variables de entorno, las API Routes, los Route Handlers, las Server Actions, el middleware, Supabase y la compatibilidad con una exportación estática.
El comando tiene esta forma:
npx next2apk analyze ./my-appEl resultado puede ser algo parecido a esto:
Project
────────────────────────────
Next.js detected
Router App Router
TypeScript yes
Supabase detected
Compatibility
────────────────────────────
Static export FAIL
Server Actions 2 detected
API Routes none
Middleware none
Recommended strategy:
REMOTELa clasificación no pretende ser magia. Es una forma de hacer explícita la arquitectura de la aplicación antes de tocarla.
STATIC, HYBRID y REMOTE
STATIC describe un proyecto que puede exportarse y empaquetarse localmente. La aplicación Android contiene los archivos generados por Next.js y puede funcionar sin levantar un servidor Next.js.
HYBRID representa una situación intermedia. Parte de la interfaz puede vivir dentro de Android, pero la aplicación depende de servicios externos. Un proyecto que utiliza Supabase directamente desde el cliente puede encajar aquí: la interfaz se empaqueta, mientras que la autenticación, la base de datos o el almacenamiento siguen estando fuera del APK.
REMOTE significa que la aplicación necesita mantener infraestructura server-side. Si existen Server Actions, API Routes, Route Handlers o lógica que requiere Node.js, no se puede fingir que todo se ha convertido en archivos estáticos. El APK puede ser una interfaz para ese servicio, pero el backend sigue necesitando un servidor.
Esta distinción es importante porque una aplicación Android no ejecuta automáticamente un backend Next.js por el hecho de estar dentro de un APK. No hay una pequeña hada de Node escondida detrás de Gradle.
Qué hacen init y build
Después del análisis llega init. Su función es preparar el proyecto de forma controlada: configura Capacitor, crea el proyecto Android cuando corresponde, sincroniza la aplicación y guarda información del proceso. También contempla backups, state.json, los gestores npm, pnpm y yarn, los modos --force y --dry-run, además de las estrategias STATIC, HYBRID y REMOTE.
npx next2apk init ./my-app --dry-run
npx next2apk init ./my-appLa opción de simulación es especialmente útil porque una herramienta que modifica proyectos debería enseñar primero qué piensa hacer. En caso de error, next2apk conserva el estado y los backups para facilitar la inspección; no pretende ocultar los cambios ni realizar una supuesta recuperación mágica.
build es la siguiente fase:
npx next2apk build ./my-app --dry-run
npx next2apk build ./my-app
npx next2apk build ./my-app --cleanEl pipeline valida de nuevo el proyecto, comprueba el entorno, ejecuta el build de Next.js cuando procede, sincroniza Capacitor, utiliza el Gradle Wrapper y busca un APK nuevo en la salida de Android. El artefacto se publica junto con un build.json que contiene metadatos como la identidad de la aplicación, la estrategia utilizada, el tamaño y el hash SHA-256.
Por ahora se trata de un pipeline de APK debug. La firma de producción, los AAB y la publicación en Google Play todavía no forman parte de lo implementado. Android distingue entre un APK de depuración y un paquete preparado para distribución; la documentación oficial explica también la diferencia entre generar un APK y un Android App Bundle. Guía oficial de compilación para lanzamiento.
El primer intento real no terminó en un APK
Esta es la parte que normalmente desaparece de los artículos sobre herramientas: el primer intento real de compilación end-to-end todavía no ha producido un APK.
El entorno de desarrollo tenía el Android SDK sin configurar y Java 25 no era compatible con el Gradle Wrapper utilizado. next2apk detectó el problema antes de iniciar una compilación incorrecta. El repositorio documenta que hay 76 tests automatizados aprobados, pero también deja claro que esos tests no sustituyen una compilación real con SDK, JDK y dispositivo o emulador.
En otras palabras: el analyzer, doctor, init y buena parte del pipeline existen; todavía estoy validando la última milla. El estado actualizado está en el repositorio de GitHub.
¿Por qué debería instalar todo esto el usuario?
La pregunta incómoda es evidente. Si la finalidad de next2apk es simplificar la creación de una aplicación Android, exigir Android Studio, Android SDK, Java y una configuración correcta de Gradle no parece precisamente una experiencia sencilla.
Ahora mismo contemplo tres posibles builders:
- Local Builder: para quien ya tiene instalado el entorno Android.
- GitHub Builder: un comando como
npx next2apk setup-cipodría generar un workflow de GitHub Actions con Node, JDK, SDK, Capacitor y Gradle, dejando el APK como artifact. - Cloud Builder: una evolución futura en la que el proyecto se analiza y compila en un entorno Android preparado, mediante CLI o una interfaz web.
La arquitectura que estoy intentando construir se parece más a esto:
Next.js
↓
Project Analyzer
↓
Compatibility Engine
↓
Build Strategy
↓
Capacitor
↓
Android + Gradle
↓
APKUn proyecto en construcción, no una promesa universal
El estado actual incluye analyze, doctor, init y build, detección de App Router y Pages Router, Supabase, middleware, Server Actions, Route Handlers, gestores de paquetes y configuración TypeScript strict. También hay fixtures, informes de texto y JSON, backups y sincronización con Capacitor.
El roadmap todavía tiene trabajo: firma de APK, generación de AAB, una posible interfaz gráfica, el modo de un solo comando y builders externos. La meta sigue siendo acercarse a:
npx next2apkPero llegar ahí implica resolver incompatibilidades reales, no esconderlas detrás de una animación de progreso.
next2apk se publica con licencia MIT y está abierto a revisión. Si te interesa convertir Next.js en APK, puedes probar el analyzer con un proyecto real, revisar el código, abrir un issue o enviar un pull request. También serán bienvenidos quienes sepan más que yo sobre Android, Gradle o Capacitor; no es una competición, y Gradle ya se encarga de suficiente drama por su cuenta.
El código y las instrucciones están en github.com/AndrewUru/next2apk. La idea no es fingir que cualquier aplicación Next.js se convierte automáticamente en Android, sino construir una herramienta que explique qué puede hacerse, qué no y por qué.