Introducción
¿Tienes una web app en Next.js? En esta guía aprenderás a convertirla en apps nativas para iOS y Android usando Capacitor 8 — la última versión con mejor rendimiento y nuevas funciones.
Capacitor envuelve tu app web en un contenedor nativo, dándote acceso a APIs del dispositivo como cámara, sistema de archivos y notificaciones push, mientras conservas tu base de código React existente. A diferencia de React Native, no necesitas reescribir nada: tu code de Next.js funciona tal cual.
Lo que aprenderás:
- Configura tu app de Next.js existente para exportación estática
- Añadir Capacitor 8 con plugins nativos esenciales
- Compilar y probar en simuladores de iOS y Android
- Activar live reload para un desarrollo más rápido
- Corregir problemas comunes de layout en iOS (viewport, safe area, horizontal overflow)
- Añade una UI con sensación nativa con Capgo Native Navigation y Transitions
¿Quieres empezar un proyecto nuevo desde cero? Mira nuestra guía sobre Crear una app móvil con Next.js desde cero.
Ventajas de usar Next.js y Capacitor
- Reutilización de Code: Next.js te permite escribir componentes reutilizables y compartir code entre tus apps web y móviles, ahorrando tiempo y esfuerzo de desarrollo.
- Rendimiento: Next.js ofrece optimizaciones de rendimiento integradas, como server-side rendering y code splitting, garantizando tiempos de carga rápidos y una experiencia de usuario fluida.
- Capacidades nativas: Capacitor da acceso a funciones nativas del dispositivo como la cámara, la geolocalización y más, permitiéndote crear apps móviles muy completas.
- Desarrollo simplificado: Con Capacitor, puedes desarrollar y probar tu app móvil usando tecnologías web que ya conoces, reduciendo la curva de aprendizaje y agilizando el proceso de desarrollo.
Requisitos
Antes de empezar, asegúrate de tener:
- Node.js 18+ instalado
- Un Next.js 15+ aplicación
- Xcode (para desarrollo de iOS, solo macOS)
- Android Studio (para desarrollo de Android)
Configuración de tu app de Next.js para móvil
El primer paso es configurar tu app de Next.js para la exportación estática. Capacitor necesita archivos HTML/JS/CSS estáticos para empaquetarlos en la app nativa.
Abre tu next.config.js (o next.config.ts) y añade la configuración de exportación:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;
El output: 'export' este ajuste le indica a Next.js que genere archivos HTML estáticos, y images: { unoptimized: true } evita la optimización de imágenes de Next.js, que requiere un servidor.
Importante: Si usas funciones que requieren un servidor (API routes, server components con data fetching, etc.), deberás refactorizarlas para usar alternativas del lado del cliente o APIs externas.
Añade scripts específicos para móviles a tu package.json:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint",
"mobile": "bun run build && bunx cap sync",
"mobile:ios": "bun run mobile && bunx cap open ios",
"mobile:android": "bun run mobile && bunx cap open android"
}
}
Prueba la exportación estática ejecutando:
bun run build
Deberías ver una carpeta out en la raíz de tu proyecto. Esta contiene todos los archivos estáticos que Capacitor empaquetará en tu app nativa.
Añadir Capacitor 8 a tu proyecto
Para empaquetar tu app de Next.js en un contenedor móvil nativo, sigue estos pasos:
- Instala Capacitor core y CLI:
bun add @capacitor/core
bun add -D @capacitor/cli
- Instala los plugins de Capacitor más comunes que probablemente necesites:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences
Estos plugins ofrecen funciones esenciales:
- @capacitor/app: Gestionar eventos del ciclo de vida (foreground/background, URLs)
- @capacitor/keyboard: Controlar el comportamiento del teclado en móviles
- @capacitor/splash-screen: Gestionar la splash screen nativa
- @capacitor/preferences: Almacenar datos clave-valor de forma persistente
- Inicializa Capacitor con los detalles de tu proyecto:
bunx cap init my-app com.example.myapp --web-dir out
Reemplazar my-app con el nombre de tu app y com.example.myapp con tu ID de app (notación de dominio inverso).
- Crea o actualiza el
capacitor.config.tsarchivo con la configuración adecuada:
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
plugins: {
SplashScreen: {
launchShowDuration: 2000,
launchAutoHide: true,
androidScaleType: 'CENTER_CROP',
showSpinner: false,
splashFullScreen: true,
splashImmersive: true,
},
},
};
export default config;
- Instala las plataformas nativas:
bun add @capacitor/ios @capacitor/android
- Añade las carpetas de las plataformas nativas:
bunx cap add ios
bunx cap add android
Capacitor creará ios y android carpetas en la raíz de tu proyecto con los proyectos nativos.
Para compilar el proyecto de Android, necesitas Android Studio. Para iOS, necesitas un Mac con Xcode.
- Haz el build y sincroniza tu proyecto:
bun run mobile
Esto ejecuta tu script personalizado que hace el build del proyecto Next.js y sincroniza los archivos estáticos con las plataformas nativas.
Build y despliegue de apps nativas
Para hacer el build y desplegar tu app móvil nativa, sigue estos pasos: Para desarrollar apps de iOS, necesitas tener Xcode instalado, y para apps de Android, necesitas tener Android Studio instalado. Además, si planeas distribuir tu app en la tienda de apps, debes inscribirte en el Apple Developer Program para iOS y en la Google Play Console para Android.
- Abre los proyectos nativos:
Para iOS:
bun run mobile:ios
Para Android:
bun run mobile:android
O directamente con Capacitor CLI:
bunx cap open ios
bunx cap open android
- Compila y ejecuta la app:

-
En Android Studio, espera a que el proyecto esté listo y luego haz clic en el botón “Run” para desplegar la app en un dispositivo conectado o emulador.

-
En Xcode, configura tu cuenta de firma para desplegar la app en un dispositivo real. Si no lo has hecho antes, Xcode te guiará a través del proceso (ten en cuenta que necesitas estar inscrito en el Apple Developer Program). Una vez configurado, haz clic en el botón “Play” para ejecutar la app en tu dispositivo conectado.
¡Felicidades! Has desplegado con éxito tu aplicación web de Next.js en un dispositivo móvil.
Live Reload con Capacitor
Durante el desarrollo, puedes aprovechar el live reloading para ver los cambios al instante en tu dispositivo móvil. Para activar esta función, sigue estos pasos:
- Busca tu dirección IP local:
-
En macOS, ejecuta el siguiente comando en la terminal:
ipconfig getifaddr en0 -
En Windows, ejecuta:
ipconfigBusca la dirección IPv4 en la salida.
- Actualiza tu
capacitor.config.tspara apuntar a tu servidor de desarrollo:
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'out',
server: {
url: 'http://YOUR_IP_ADDRESS:3000',
cleartext: true,
},
};
export default config;
Reemplazar YOUR_IP_ADDRESS con tu dirección IP local (ej., 192.168.1.100).
- Aplica los cambios a tu proyecto nativo:
bunx cap copy
El copy El comando copia la carpeta web y los cambios de configuración al proyecto nativo sin actualizar todo el proyecto.
- Recompila y ejecuta la app en tu dispositivo usando Android Studio o Xcode.
Ahora, cada vez que hagas cambios en tu app de Next.js, la app móvil se recargará automáticamente para reflejarlos.
Nota: Si instalas nuevos plugins o haces cambios en archivos nativos, deberás recompilar el proyecto nativo, ya que el live reloading solo aplica a cambios web code.
Uso de Capacitor Plugins
Los plugins de Capacitor te permiten acceder a funciones nativas del dispositivo desde tu app de Next.js. Veamos cómo usar el plugin Share como ejemplo:
- Instala el plugin Share:
bun add @capacitor/share
- Actualiza el
pages/index.jsarchivo para usar el plugin Share:
import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';
export default function Home() {
const share = async () => {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends',
});
};
return (
<div className={styles.container}>
<Head>
<title>Create Next App</title>
<meta name="description" content="Generated by create next app" />
<link rel="icon" href="/favicon.ico" />
</Head>
<main className={styles.main}>
<h1 className={styles.title}>
Welcome to <a href="https://nextjs.org">Capgo!</a>
</h1>
<p className={styles.description}>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</main>
</div>
);
}
- Sincroniza los cambios con el proyecto nativo:
Como mencionamos antes, al instalar nuevos plugins, debemos hacer un sync y luego volver a desplegar la app en nuestro dispositivo. Para ello, ejecuta el siguiente comando:
bun run mobile
O simplemente sincroniza sin recompilar:
bunx cap sync
- Recompila y ejecuta la app en tu dispositivo.
Ahora, al hacer clic en el botón «Compartir ahora», aparecerá el diálogo de compartir nativo, lo que te permitirá compartir el contenido con otras apps.
He trabajado durante años con Ionic para construir aplicaciones multiplataforma, pero integrarlo con Next.js es engorroso y rara vez vale la pena cuando ya tienes Tailwind CSS 4.
Para lograr una sensación nativa en una app de Next.js + Capacitor, usa plugins de Capgo en lugar de kits de UI solo para web como Konsta UI:
- @capgo/capacitor-native-navigation — navbar nativa, barra de pestañas Liquid Glass en iOS y estilo de barra de pestañas difuminada en Android. Tu router de Next.js mantiene el estado de las rutas; el plugin se encarga del chrome nativo.
- @capgo/capacitor-transitions — transiciones de página estilo Ionic y swipe-back desde el borde en iOS en la capa WebView, sin adoptar Ionic UI.
Instala ambos:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync
Configura la navegación nativa con CSS inset mode para que el contenido web respete las barras nativas:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});
Renderiza una tab bar Liquid Glass (iOS usa renderizado del sistema; Android usa un fondo WebView con desenfoque):
await NativeNavigation.setTabbar({
selectedId: 'home',
labelVisibilityMode: 'labeled',
icons: true,
colors: { dynamic: true },
tabs: [
{ id: 'home', title: 'Home', icon: { svg: '...' } },
{ id: 'settings', title: 'Settings', icon: { svg: '...' } },
],
});
await NativeNavigation.addListener('tabSelect', ({ id }) => {
router.push(`/${id}`);
});
Añade transiciones de página nativas en tu app shell:
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
Envuelve las páginas enrutadas en cap-router-outlet, cap-page, y cap-content, y llama a setDirection('forward') o setDirection('back') antes router.push() o router.back(). No dupliques las cabeceras ni los pies de página web cuando la navegación nativa gestione esas superficies.
Consulta las guías completas: Uso de @capgo/capacitor-native-navigation y Uso de @capgo/capacitor-transitions.
Safe areas con Tailwind
Para las safe areas del dispositivo en Tailwind CSS, usa @capgo/tailwind-capacitor (publicado como tailwind-capacitor en npm). Proporciona safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor:
bun add -D tailwind-capacitor
En styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";
Usa utilidades como pt-safe, pb-safe, y px-safe en lugar de añadir env(safe-area-inset-*) manualmente. El proyecto está en desarrollo activo — si falta algo para tu configuración de Next.js, abre un PR en GitHub.
Cómo solucionar problemas de layout en iOS (viewport, safe area y overflow horizontal)
Si el contenido se ve recortado, desplazado o con scroll horizontal en iOS, añadir más overflow-x: hidden o ajustar solo la etiqueta viewport no suele solucionarlo. Revisa estas comprobaciones en orden.
Asegúrate de que la meta tag viewport esté bien aplicada
App Router (app/): export viewport de los app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};
Pages Router (pages/): coloca la etiqueta meta viewport en pages/_app.tsx, no _document.tsx (Next.js puede no aplicar las etiquetas desde _document.tsx de la forma que esperas para el comportamiento del viewport).
Gestiona el safe area de iOS desde un único wrapper raíz
Crea un único app shell y aplica el padding de safe area ahí, no en múltiples componentes anidados:
html,
body,
#__next {
width: 100%;
min-height: 100%;
margin: 0;
padding: 0;
overflow-x: hidden;
}
* {
box-sizing: border-box;
}
.app-shell {
min-height: 100dvh;
width: 100%;
padding-top: env(safe-area-inset-top);
padding-right: env(safe-area-inset-right);
padding-bottom: env(safe-area-inset-bottom);
padding-left: env(safe-area-inset-left);
}
Envuelve todo el contenido de la página dentro de .app-shell. El padding de safe-area duplicado en headers, modales y wrappers de layout suele hacer que la UI parezca recortada o demasiado grande.
Con @capgo/tailwind-capacitor, puedes aplicar el mismo padding usando utilidades como pt-safe pb-safe px-safe en ese único shell.
Configura Capacitor iOS contentInset a never primero
En capacitor.config.ts, prefiere desactivar el inset nativo y dejar que CSS (o la navegación nativa) contentInsetMode: 'css') se encargue del safe area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};
Combinar el content inset automático de Capacitor con CSS env(safe-area-inset-*) es una causa común de espaciado doble.
Encuentra el elemento que realmente desborda
El culpable habitual es un elemento que usa 100vw, Tailwind w-screen, un ancho fijo en píxeles, o un min-width.
En Safari Web Inspector, ejecuta:
[...document.querySelectorAll('*')]
.filter(el => el.scrollWidth > document.documentElement.clientWidth)
.map(el => ({
el,
tag: el.tagName,
class: el.className,
scrollWidth: el.scrollWidth,
clientWidth: document.documentElement.clientWidth,
}));
Con Tailwind, reemplaza w-screen con w-full siempre que sea posible. Muchos problemas de desbordamiento horizontal vienen de 100vw / w-screen, padding de safe-area duplicado o un contenedor de ancho fijo, no del propio meta tag del viewport.
Optimización del rendimiento
Para garantizar el rendimiento óptimo de tu app de Next.js y Capacitor, considera las siguientes mejores prácticas:
- Minimiza el tamaño de la app eliminando dependencias y assets no utilizados.
- Optimiza las imágenes y otros archivos multimedia para reducir los tiempos de carga.
- Implementa carga diferida para componentes y páginas para mejorar el rendimiento de la carga inicial.
- Usa server-side rendering (SSR) con Next.js para mejorar la velocidad de carga y el SEO de la app.
- Aprovecha las optimizaciones integradas de Capacitor, como la caché de web view y el bundling de la app.
Conclusión
Has convertido con éxito tu aplicación web existente de Next.js en apps nativas para iOS y Android usando Capacitor 8. Tu base de código web ahora se ejecuta de forma nativa en dispositivos móviles con acceso a las APIs del dispositivo.
Lo que lograste:
- Configuraste Next.js para exportación estática
- Añadiste Capacitor 8 con los plugins esenciales
- Compilaste y desplegaste en los simuladores de iOS y Android
- Activaste la recarga en vivo para desarrollo
- Corregiste problemas comunes de diseño en iOS (viewport, safe area, overflow)
- Añadiste una UI con sensación nativa usando Capgo Native Navigation y Transitions
Próximos pasos:
- Configura Capgo para actualizaciones over-the-air sin reenviar a la tienda de aplicaciones
- Añade más plugins nativos como Cámara, Geolocalización o Notificaciones Push
- Configura iconos de app y pantallas de inicio para producción
- Prepara tu app para el envío a App Store y Google Play
¿Empezando un proyecto nuevo? Echa un vistazo a Construir una app móvil con Next.js desde cero para una guía paso a paso.
Recursos
- Documentación de Next.js
- @capgo/capacitor-native-navigation — Barra de pestañas Liquid Glass y chrome nativo
- Documentación de Capacitor 8
- @capgo/capacitor-transitions — transiciones de página con estilo nativo
- @capgo/tailwind-capacitor — Utilidades safe-area de Tailwind para Capacitor
- Capgo - Live Updates para apps de Capacitor
Descubre cómo Capgo puede ayudarte a crear mejores apps más rápido: crea una cuenta gratis hoy.
Preguntas frecuentes
¿Cómo convierto una app de Next.js en una app móvil?
Configura output: 'export' en next.config para que Next.js genere un sitio estático, añade Capacitor y las plataformas iOS y Android, apunta webDir a la carpeta out, luego ejecuta npx cap sync y abre los proyectos nativos. Las funciones exclusivas de servidor, como las rutas API, deben moverse a un backend separado. Después del lanzamiento, actualizaciones Live Update de Capgo publica cambios web sin una nueva revisión de la tienda.
Continúa desde Convertir tu app de Next.js a iOS y Android con Capacitor 8
Si estás usando Convierte tu app de Next.js a iOS y Android con Capacitor 8 para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo en Alternativas a plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds.