Introduction
¿Tiene una aplicación web Next.js existente? En esta guía, aprenderá a transformarla en aplicaciones móviles nativas de iOS y Android utilizando Capacitor 8 — la última versión con mejoras de rendimiento y nuevas características.
Capacitor envuelve su aplicación web en un contenedor nativo, le da acceso a APIs de dispositivo como cámara, sistema de archivos y notificaciones push, mientras mantiene su código React existente. A diferencia de React Native, no necesita reescribir nada — su Next.js code se ejecuta tal cual.
¿Qué aprenderá?:
- Configure su aplicación Next.js existente para exportación estática
- Agregar Capacitor 8 con plugins nativos esenciales
- Crear y probar en simuladores de iOS y Android
- Habilitar recarga en vivo para un desarrollo más rápido
- Corregir problemas de diseño comunes de iOS (viewport, área segura, desbordamiento horizontal)
- Agregar una interfaz de usuario que sienta como si fuera nativa con Capgo Native Navigation y Transitions
¿Buscas empezar un nuevo proyecto desde cero? Construyendo una aplicación móvil de Next.js desde cero.
Ventajas de utilizar Next.js y Capacitor
- Code ReutilizaciónReutilización de componentes: Next.js te permite escribir componentes reutilizables y compartir code entre tus aplicaciones web y móviles, ahorrando tiempo y esfuerzo en el desarrollo.
- RendimientoNext.js ofrece optimizaciones de rendimiento integradas, como la renderización del lado del servidor y code de fragmentación, garantizando tiempos de carga rápidos y una experiencia de usuario suave.
- Capacidades nativas Capacitor proporciona acceso a características de dispositivos nativos como la cámara, la geolocalización y más, permitiéndote construir aplicaciones móviles ricas en características.
- Desarrollo simplificadoCon Capacitor, puedes desarrollar y probar tu aplicación móvil utilizando tecnologías web familiares, reduciendo la curva de aprendizaje y simplificando el proceso de desarrollo.
Requisitos previos
Antes de empezar, asegúrese de tener:
- Node.js 18+ instalado
- Una aplicación existente Next.js 15+ Xcode
- (solo para desarrollo de iOS en macOS) Android Studio
- (solo para desarrollo de Android) Configurando su aplicación Next.js para móviles
El primer paso es configurar su aplicación Next.js para exportación estática. __CAPGO_KEEP_0__ necesita archivos HTML/JS/CSS estáticos para empaquetar en la aplicación nativa.
Capacitor
Abre tu next.config.js (o next.config.ts) archivo y agrega la configuración de exportación:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;La output: 'export' configuración 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 estás utilizando características que requieren un servidor (rutas API, componentes de servidor con recuperación de datos, etc.), necesitarás refactorizar esas características para utilizar alternativas de lado del cliente o APIs externas.
Agrega 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 buildDeberías ver un out carpeta en la raíz de tu proyecto. Esta contiene todos los archivos estáticos que Capacitor empaquetará en tu aplicación nativa.
Agregar Capacitor 8 a su proyecto
Para empaquetar su aplicación Next.js en un contenedor móvil nativo, siga estos pasos:
- Instale Capacitor core y CLI:
bun add @capacitor/core
bun add -D @capacitor/cli- Instale los plugins Capacitor comunes que probablemente necesitará:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesEstos plugins proporcionan características esenciales:
- @capacitor/app: Maneje eventos de ciclo de vida de la aplicación (anterior/plano, URLs)
- @capacitor/teclado: Controlar el comportamiento del teclado en móviles
- @capacitor/pantalla de bienvenida: Administrar la pantalla de bienvenida nativa
- @capacitor/preferencias: Almacene datos clave-valor persistentemente
- Inicialice Capacitor con los detalles de su proyecto:
bunx cap init my-app com.example.myapp --web-dir outSustituya my-app por el nombre de su aplicación y com.example.myapp por el ID de su aplicación (notación de dominio inverso).
- Crear o actualizar 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;- Instale plataformas nativas:
bun add @capacitor/ios @capacitor/android- Agregue las carpetas de plataforma nativa:
bunx cap add ios
bunx cap add androidCapacitor creará ios y android carpetas en la raíz de su proyecto que contengan los proyectos nativos.
Para construir el proyecto de Android, necesitas Android Studio. Para iOS, necesitas un Mac con Xcode.
- Construye y sincroniza tu proyecto:
bun run mobileEjecuta tu script personalizado que construye el proyecto de Next.js y sincroniza los archivos estáticos con las plataformas nativas.
Desarrollar y Desplegar Aplicaciones Móviles Nativas
Para construir y desplegar tu aplicación móvil nativa, sigue estos pasos: Para desarrollar aplicaciones de iOS, necesitas tener Xcode instalado, y para aplicaciones de Android, necesitas tener Android Studio instalado. Además, si planeas distribuir tu aplicación en la tienda de aplicaciones, necesitas inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android.
- Abra los proyectos nativos:
Para iOS:
bun run mobile:iosPara Android:
bun run mobile:androidO directamente con Capacitor CLI:
bunx cap open ios
bunx cap open android- Construya y ejecute la aplicación:
-
En Android Studio, espere a que el proyecto esté listo, y luego haga clic en el botón “Ejecutar” para desplegar la aplicación en un dispositivo conectado o emulador.
-
En Xcode, configure su cuenta de firma para desplegar la aplicación en un dispositivo real. Si no lo ha hecho antes, Xcode le guiará a través del proceso (tenga en cuenta que necesita estar inscrito en el Programa de Desarrolladores de Apple). Una vez configurado, haga clic en el botón “Reproducir” para ejecutar la aplicación en su dispositivo conectado.
¡Felicidades! Ha desplegado con éxito su aplicación web de Next.js en un dispositivo móvil.
Capacitor Live Reload
Durante el desarrollo, puede aprovechar el recarga en vivo para ver los cambios de manera instantánea en su dispositivo móvil. Para habilitar esta característica, siga estos pasos:
- Encuentre su dirección IP local:
-
En macOS, ejecute el siguiente comando en la terminal:
ipconfig getifaddr en0 -
En Windows, ejecute:
ipconfigBusque la dirección IPv4 en el resultado.
- Actualice su
capacitor.config.tspara que apunte a su 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;Sustituya YOUR_IP_ADDRESS por su dirección IP local (por ejemplo, 192.168.1.100).
- Aplicar los cambios a su proyecto nativo:
bunx cap copyEl copy copiar el folder web y los cambios de configuración al proyecto nativo sin actualizar todo el proyecto.
- Reconstruye y ejecuta la aplicación en tu dispositivo utilizando Android Studio o Xcode.
Ahora, cada vez que realices cambios en tu aplicación Next.js, la aplicación móvil se recargará automáticamente para reflejar esos cambios.
Nota: Si installas nuevos plugins o realizas cambios en archivos nativos, deberás reconstruir el proyecto nativo ya que la recarga en vivo solo se aplica a cambios web code.
Usando Capacitor Plugins
Los plugins Capacitor te permiten acceder a características de dispositivos nativos desde tu aplicación Next.js. Exploraremos cómo utilizar el plugin de Compartir como ejemplo:
- Instala el plugin de Compartir:
bun add @capacitor/share- Actualiza el
pages/index.jsarchivo para utilizar el plugin de Compartir:
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:
As mencionado anteriormente, cuando instalamos nuevos plugins, debemos realizar una operación de sincronización y luego volver a desplegar la aplicación en nuestro dispositivo. Para hacer esto, ejecute el siguiente comando:
bun run mobileO simplemente sincronice sin reconstruir:
bunx cap sync- Reconstruya y ejecute la aplicación en su dispositivo.
Ahora, cuando haga clic en el botón 'Compartir ahora!', se mostrará el diálogo de compartir nativo, lo que le permitirá compartir el contenido con otras aplicaciones.
## Interfaz de usuario que se siente nativa con __CAPGO_KEEP_1__ Navegación y Transiciones Nativas He trabajado durante años con Ionic para construir aplicaciones de múltiples plataformas, pero integrarla con Next.js es una solución hackeada y raramente vale la pena cuando ya tiene.
For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- Para un sentir móvil nativo en una aplicación Next.js + capgo, utilice en su lugar capacitor plugins en lugar de kits de interfaz de usuario web solo como Konsta UI: – barra de navegación nativa, Liquid Glass de pestañas en iOS, y un estilo de pestañas difuminado en Android. Su router Next.js mantiene el estado de la ruta; el complemento posee el navegador nativo.
- @capgo/capacitor-transiciones – transiciones de página estilo Ionic y retroceso de arrastre en iOS en la capa WebView, sin adoptar la interfaz de usuario de Ionic.
Instale ambos:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigure la navegación nativa con el modo de inserción de CSS 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',
},
});Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propia del sistema; Android utiliza un fondo difuminado de WebView):
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}`);
});Agregue transiciones de página nativas en su capa de concha de la aplicación:
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });Envuelva las páginas de rutas en cap-router-outlet, cap-page, y cap-content, y llame a setDirection('forward') o setDirection('back') antes de router.push() o router.back()No duplique encabezados o pie de página web cuando la navegación nativa controla esas superficies.
Consulte las guías completas: Usando @capgo/capacitor-navegación-nativa y Usando @capgo/capacitor-transiciones.
Áreas seguras con Tailwind
Para áreas seguras de dispositivos en Tailwind CSS, utilice @capgo/tailwind-capacitor (publicado como tailwind-capacitor en npm). Proporciona safe-areas utilidades y otros plugins de Tailwind amigables con Capacitor:
bun add -D tailwind-capacitorEn styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilice herramientas como pt-safe, pb-safe, y px-safe en lugar de agregar env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para su configuración de Next.js, abre una PR en GitHub.
Problemas de diseño de iOS (Viewport, Área Segura y Desbordamiento Horizontal)
Si el contenido parece recortado, desplazado o desplazable horizontalmente en iOS, agregar más overflow-x: hidden o ajustar la etiqueta de viewport sola no suele solucionarlo. Pase por estos controles en orden.
Asegúrese de que la etiqueta meta de viewport se aplique correctamente
App Router (app/): export viewport desde app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};Ruta de Páginas (pages/): coloque la etiqueta de meta de viewport en pages/_app.tsx, no _document.tsx (Next.js puede no aplicar etiquetas de la forma en que se espera para el comportamiento de la vista). _document.tsx Administre el área seguro de iOS desde un solo envoltorio raíz
Crear un solo concha de aplicación y aplique allí el relleno de área segura — no en múltiples componentes anidados:
Envuelva todo el contenido de la página dentro de
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);
}El relleno de área segura duplicado en encabezados, modales y envolturas de diseño a menudo hace que la interfaz de usuario se vea recortada o demasiado grande. .app-shellCon
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorPuede expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola consola.
Establezca Capacitor iOS contentInset a never primero
En capacitor.config.ts, prefiera el relleno nativo deshabilitado y deja que CSS (o la navegación nativa ‘) tenga el área segura: contentInsetMode: 'css'Mezclar el relleno de contenido automático de __CAPGO_KEEP_0__ con CSS
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Encuentre el elemento que realmente está desbordando
El culpable usual es un elemento que utiliza
Mixing __CAPGO_KEEP_0__’s automatic content inset with CSS 100vwTailwind w-screeno ancho de píxeles fijo, o un ancho grande min-width.
In Safari Web Inspector, ejecutar:
[...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 cuando sea posible. Muchos problemas de rebosamiento horizontal provienen de 100vw / w-screenduplicado relleno de área segura, o un contenedor de ancho fijo — no del meta etiqueta de viewport en sí.
Optimización de Rendimiento
Para asegurar el rendimiento óptimo de tu aplicación Next.js y Capacitor, considera las siguientes prácticas recomendadas:
- Minimiza el tamaño de la aplicación eliminando dependencias y recursos innecesarios.
- Optimiza las imágenes y otros archivos de medios para reducir los tiempos de carga.
- Implementa la carga diferida para componentes y páginas para mejorar el rendimiento de carga inicial.
- Utilice la renderización del lado del servidor (SSR) con Next.js para mejorar la velocidad de carga de la aplicación y la optimización para motores de búsqueda (SEO).
- Utilice las optimizaciones integradas de Capacitor, como la caché de la vista web y el empaquetado de la aplicación.
Conclusión
Ha convertido con éxito su aplicación web existente de Next.js en aplicaciones nativas de iOS y Android utilizando Capacitor 8. Ahora su código web se ejecuta de manera nativa en dispositivos móviles con acceso a APIs de dispositivo.
Lo que ha logrado:
- Configuró Next.js para exportación estática
- Agregó Capacitor 8 con plugins esenciales
- Creó y desplegó a simuladores de iOS y Android
- Habilitó la recarga en vivo para el desarrollo
- Corrigió problemas de diseño comunes de iOS (viewport, área segura, rebosamiento)
- Agregó una interfaz de usuario que siente como si fuera nativa con Capgo Native Navigation y Transiciones
Pasos siguientes:
- Configuración Capgo para actualizaciones por aire sin reenvío a la tienda de aplicaciones
- Agregar más plugins nativos como Cámara, Geolocalización o Notificaciones de Puesta en Marcha
- Configurar iconos de aplicación y pantallas de bienvenida para producción
- Preparar su aplicación para la presentación en la Tienda de Mac y Google Play
Iniciando un proyecto nuevo? Consulte Creando una aplicación móvil de Next.js desde cero para una guía paso a paso.
Recursos
- Documentación de Next.js
- @capgo/capacitor-navegación-nativa — Barra de pestañas de vidrio líquido y navegador nativo
- Capacitor 8 Documentación
- @capgo/capacitor-transiciones — Transiciones de página que se sienten nativas
- @capgo/tailwind-capacitor — Utilidades de área segura de Tailwind para Capacitor
- Capgo - Actualizaciones en vivo para aplicaciones Capacitor
Aprende cómo Capgo puede ayudarte a construir aplicaciones mejoradas más rápido regístrate para una cuenta gratuita hoy.
Sigue adelante desde Convertir tu aplicación Next.js a iOS & Android con Capacitor 8
Si estás utilizando Convierta su aplicación Next.js a iOS & Android con Capacitor 8 para planificar el trabajo de plugin nativo, conectéalo con Capgo Directorio de Plugin para el flujo de trabajo del producto en Capgo Directorio de Plugin, Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise, y Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas.
