Convertir su aplicación Next.js a iOS y Android con Capacitor 8

Introducción

Tenga una aplicación web Next.js existente? En este guía, aprenderá a transformarla en aplicaciones móviles nativas de iOS y Android utilizando Capacitor 8 — la última versión con mejor rendimiento y nuevas características.

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing React codebase. Unlike React Native, you don’t need to rewrite anything — your Next.js code runs as-is.

¿Qué aprenderás:

Configura tu aplicación Next.js existente para exportación estática
Agregar Capacitor 8 con plugins nativos esenciales
Agregar __CAPGO_KEEP_0__ 8 con plugins nativos esenciales
Activar recarga en vivo para un desarrollo más rápido
Corregir problemas de diseño comunes de iOS (viewport, zona segura, rebosamiento horizontal)
Agregar una interfaz de usuario que se sienta nativa con Capgo Navegación y Transiciones nativas

¿Buscas empezar un nuevo proyecto desde cero? Revisa nuestra guía sobre Crear una aplicación móvil de Next.js desde cero.

Ventajas de usar Next.js y Capacitor

Code Reutilización: Next.js te permite escribir componentes reutilizables y compartir code entre tus aplicaciones web y móviles, ahorrando tiempo y esfuerzo de desarrollo.
Rendimiento: Next.js ofrece optimizaciones de rendimiento integradas, como renderizado en servidor y fragmentación de code, garantizando tiempos de carga rápidos y una experiencia de usuario suave.
Capacidades Nativas: Capacitor ofrece acceso a características de dispositivos nativos como la cámara, la geolocalización y más, permitiéndote crear aplicaciones móviles ricas en funcionalidades.
Desarrollo Simplificado: Con Capacitor, puede desarrollar y probar su aplicación móvil utilizando tecnologías web familiares, reduciendo la curva de aprendizaje y simplificando el proceso de desarrollo.

Requisitos previos

Antes de comenzar, asegúrese de tener:

Node.js 18+ instalado
Un existente Next.js 15+ Xcode
Xcode (para el desarrollo de iOS, solo macOS)
Android Studio (para el desarrollo de Android)

Configuración de tu aplicación Next.js para móviles

El primer paso es configurar tu aplicación Next.js para exportación estática. Capacitor necesita archivos HTML/JS/CSS estáticos para empaquetar en la aplicación nativa.

Abre tu next.config.js archivo (o next.config.tsarchivo) 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 (API rutas, componentes de servidor con recuperación de datos, etc.), necesitarás refactorizarlas 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 build

Deberí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 Tu Proyecto

Para empaquetar tu aplicación 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 plugins comunes de Capacitor que probablemente necesitarás:

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences

Estos plugins proporcionan características esenciales:

@capacitor/appGestionar eventos de ciclo de aplicación (anterior/plano, URLs)
@capacitor/teclado: Controla el comportamiento del teclado en móviles
@capacitor/pantalla-de-inicio: Administra la pantalla de inicio nativa
@capacitor/preferencias: Almacena datos clave-valor de manera persistente

Inicializa Capacitor con detalles de tu proyecto:

bunx cap init my-app com.example.myapp --web-dir out

Sustituye my-app con el nombre de tu aplicación y com.example.myapp con el ID de tu aplicación (notación de dominio inverso).

Crea o actualiza el capacitor.config.ts archivo 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 plataformas nativas:

bun add @capacitor/ios @capacitor/android

Agrega carpetas de plataforma nativa:

bunx cap add ios
bunx cap add android

Capacitor creará ios y android carpetas en la raíz de tu proyecto que contienen 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 mobile

Esto ejecuta tu script personalizado que construye el proyecto Next.js y sincroniza los archivos estáticos con las plataformas nativas.

Construyendo y Desplegando Aplicaciones 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, debes inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play 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

Construye y ejecuta la aplicación:

android-studio-run

En Android Studio, espera a que el proyecto esté listo, y luego haz clic en el botón ‘Ejecutar’ para desplegar la aplicación en un dispositivo conectado o emulador.
En Xcode, configura tu cuenta de firma para desplegar la aplicación en un dispositivo real. Si no lo has hecho antes, Xcode te guiará a través del proceso (ten en cuenta que debes estar inscrito en el Programa de Desarrolladores de Apple). Una vez configurado, haz clic en el botón ‘Reproducir’ para ejecutar la aplicación en tu dispositivo conectado.

¡Felicidades! Has desplegado con éxito tu aplicación web de Next.js en un dispositivo móvil.

Pero espera, hay una forma más rápida de hacer esto durante el desarrollo...

Capacitor Recarga en vivo

Durante el desarrollo, puedes aprovechar la recarga en vivo para ver los cambios de manera instantánea en tu dispositivo móvil. Para habilitar esta característica, sigue estos pasos:

Encuentra tu dirección IP local:

En macOS, ejecuta el siguiente comando en la terminal:
```
ipconfig getifaddr en0
```
En Windows, ejecuta:
```
ipconfig
```
Busca la dirección IPv4 en la salida.

actualiza tu capacitor.config.ts a que apunte 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;

Sustituye YOUR_IP_ADDRESS con tu dirección IP local (por ejemplo, 192.168.1.100).

Aplica los cambios a tu proyecto nativo:

bunx cap copy

La copy comando copia el folder web y los cambios de configuración al proyecto nativo sin actualizar el proyecto completo.

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 instales 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 Capacitor plugins te permiten acceder a características de dispositivos nativos desde tu aplicación Next.js. Exploraremos cómo utilizar el plugin Compartir como ejemplo:

Instala el plugin Compartir:

bun add @capacitor/share

Actualizar el pages/index.js archivo 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>
  );
}

Sincronizar los cambios con el proyecto nativo:

Como se mencionó anteriormente, al instalar nuevos plugins, debemos realizar una operación de sincronización y luego volver a desplegar la aplicación en nuestro dispositivo. Para hacer esto, ejecuta el siguiente comando:

bun run mobile

O simplemente sincroniza sin reconstruir:

bunx cap sync

Reconstruye y ejecuta la aplicación en tu dispositivo.

Ahora, cuando hagas clic en el botón 'Compartir ahora!', se mostrará el diálogo de compartir nativo, permitiéndote compartir el contenido con otras aplicaciones.

En segundo lugar, puedes hacer que la aplicación se sienta más nativa en iOS y Android con Capgo de navegación y transiciones, y solucionar problemas de diseño comunes de iOS que causan rebosamiento horizontal o áreas de seguridad recortadas. ## UI nativa con Capgo 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 engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS 4.

Para un sentir móvil nativo en una aplicación Next.js + Capacitor, utilice plugins Capgo en lugar de kits de interfaz de usuario web solo como Konsta UI:

@capgo/capacitor-navegación-nativa — barra de navegación nativa, Liquid Glass barra de pestañas en iOS, y un estilo de barra de pestañas difuminado en Android. Su router Next.js mantiene el estado de ruta; el plugin posee el navegador nativo.
@capgo/capacitor-transiciones — Transiciones de página estilo Ionic y retroceso por swipe 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 sync

Configura la navegación nativa con el modo de inserción 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',
  },
});

Render un tablero de Liquid Glass (iOS utiliza la renderización propia del sistema; Android utiliza un fondo de fondo de WebView desenfocado):

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:

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

Envuelva páginas de ruta en cap-router-outlet, cap-pagey cap-contenty llamar setDirection('forward') o setDirection('back') o router.push() o router.back()No dupliquen los encabezados o pie de página web cuando la navegación nativa controla esas superficies.

Ver los guías completas: Usando @capgo/capacitor-navegación nativa y Usando @capgo/capacitor-transiciones.

Zonas de seguridad con Tailwind

Para áreas de seguridad de dispositivo en Tailwind CSS, utilice @capgo/tailwind-capacitor (publicado como) tailwind-capacitor en npm). Ofrece 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";

Utiliza utilidades como pt-safe, pb-safe, y px-safe en lugar de agregarlas env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de Next.js, abre una solicitud de extracción en GitHub.

Solucionar 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 solucionar el problema. Pasa por estas comprobaciones 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',
};

Rutas de Páginas (pages/): coloque la etiqueta meta de viewport en pages/_app.tsx, no _document.tsx (Next.js puede no aplicar etiquetas de) _document.tsx Administre el área seguro de iOS desde un solo wrapper raíz

Maneja el área segura de iOS desde un wrapper raíz solo.

Cree un contenedor de aplicación único y aplique allí el relleno de área segura — 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);
}

Wrap all page content inside __CAPGO_KEEP_0__ .app-shell. El relleno de área segura duplicado en encabezados, modales y wrappers de diseño suele hacer que la interfaz de usuario parezca recortada o demasiado grande.

Con @capgo/tailwind-capacitor, puedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola capa.

Establece Capacitor iOS `contentInset` a `never` primero

En capacitor.config.ts, prefiera el diseño nativo deshabilitado y deja CSS (o la navegación nativa) contentInsetMode: 'css') tenga el área segura:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

Mezclar Capacitor’s contenido de área de inserción automático con CSS env(safe-area-inset-*) El relleno es una causa común de doble espaciado.

Encuentre el elemento que sobresale

El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screenuna anchura de píxel fija, o una gran 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 cuando sea posible. Muchos problemas de desbordamiento horizontal provienen de 100vw / w-screen, duplicado relleno de área segura, o un contenedor de ancho fijo — no del meta de etiqueta de viewport en sí.

Optimización de rendimiento

Para garantizar el rendimiento óptimo de tu aplicación Next.js y Capacitor, considera las siguientes prácticas recomendadas.

Minimice el tamaño de la aplicación eliminando dependencias y recursos no utilizados.
Optimice imágenes y otros archivos de medios para reducir los tiempos de carga.
Implemente la carga difusa para componentes y páginas para mejorar el rendimiento de carga inicial.
Utilice el servidor para renderizar (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 caché de vista web y empaquetado de aplicaciones.

Conclusión

Ha logrado convertir 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 nativamente 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
Compiló y desplegó en simuladores de iOS y Android
Habilitó la recarga en vivo para el desarrollo
Resolvió problemas de diseño comunes de iOS (viewport, zona segura, rebosamiento)
Agregó una interfaz de usuario que siente como nativa con Capgo Navegación y Transiciones nativas

Próximos pasos:

Configuración Capgo actualizaciones por aire sin reenvío a la tienda de aplicaciones
Agregar más plugins nativos como Cámara, Ubicación o Notificaciones Push
Configurar iconos de aplicación y pantallas de bienvenida para producción
Prepárate tu aplicación para la presentación en App Store y Google Play

Empezando un proyecto nuevo? Consulte Crear 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 con un sentimiento nativo
@capgo/tailwind-capacitor --- Utilidades de área segura de Tailwind para Capacitor
Capgo - Live Updates for Capacitor Apps

Aprende cómo Capgo puede ayudarte a crear aplicaciones mejoradas más rápido regístrate para una cuenta gratuita Hoy.

Sigue adelante desde Convertir tu aplicación de Next.js a iOS y Android con Capacitor 8

Si estás utilizando Convertir tu aplicación de Next.js a iOS y Android con Capacitor 8 Para planificar el trabajo de plugin nativo, conecta con Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, Capacitor Plugins por Capgo para los detalles de implementación en Capacitor Plugins por Capgo, Agregar o Actualizar Plugins para los detalles de implementación en Agregar o Actualizar Plugins, Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternatives, y Capgo Construcción Nativa para el flujo de trabajo del producto en Capgo Construcción Nativa.

Convierte tu aplicación Next.js en iOS y Android con Capacitor 8