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

Introducción

Tienes una aplicación web Next.js existente? En este guía, aprenderás a transformarla en aplicaciones móviles nativas iOS y Android utilizando Capacitor 8 — la última versión con mejoras de 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
Add Capacitor 8 with essential native plugins
Construye y prueba en simuladores iOS y Android
Habilita recarga en vivo para un desarrollo más rápido
Corrige problemas de diseño comunes de iOS (viewport, área segura, desbordamiento horizontal)
Add native-feeling UI with Capgo Native Navigation and Transitions

¿Buscas empezar un nuevo proyecto desde cero? Crear una aplicación móvil de Next.js desde cero.

Benefits of Using Next.js and Capacitor

Code Reusability: Next.js enables you to write reusable components and share code between your web and mobile apps, saving development time and effort.
Rendimiento: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
: Next.js ofrece optimizaciones de rendimiento integradas, como renderizado en servidor y fragmentación de código, asegurando tiempos de carga rápidos y una experiencia de usuario suave.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
: Capacitor proporciona acceso a características de dispositivo nativas como la cámara, la geolocalización y más, permitiéndote crear aplicaciones móviles ricas en características.: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

: Con 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.

Antes de empezar, asegúrese de tener:

Node.js 18+ instalado
Un proyecto de Next.js 15+ aplicación existente
Xcode (solo para desarrollo de iOS en macOS)
Android Studio (solo para desarrollo de Android)

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

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

Abra su next.config.js (o next.config.ts) archivo y agregue 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á utilizando características que requieren un servidor (rutas API, componentes de servidor con recuperación de datos, etc.), deberá refactorizarlas para utilizar alternativas de lado del cliente o APIs externas.

Agregue scripts específicos de móvil a su 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"
  }
}

Pruebe la exportación estática ejecutando:

bun run build

Debería ver un out carpeta en la raíz de su proyecto. Este contiene todos los archivos estáticos que Capacitor empaquetará en su 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 de Capacitor comunes que probablemente necesitará:

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

Estos plugins proporcionan características esenciales:

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

Inicializa Capacitor con los detalles de tu proyecto:

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

Sustituye my-app por el nombre de tu aplicación y com.example.myapp por 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 las 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.

To 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 de Next.js y sincroniza los archivos estáticos con las plataformas nativas.

Desarrollar y Desplegar 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, 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:ios

Para Android:

bun run mobile:android

O directamente con Capacitor CLI:

bunx cap open ios
bunx cap open android

Construya y ejecute la aplicación:

android-studio-run

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.

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

Capacitor Live Reload

Durante el desarrollo, puede aprovechar la 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:
```
ipconfig
```
Busque la dirección IPv4 en la salida.

Actualice su capacitor.config.ts para 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 copy

El copy La orden 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 instala nuevos plugins o realiza cambios en archivos nativos, necesitará 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

Actualiza el pages/index.js archivo para utilizar el plugin 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 mobile

O 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.

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas. ## Native-feeling UI with Capgo Native Navigation and Transitions

## 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 engorrosa 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: @capgo/capacitor-native-navigation --- menú nativo, barra de pestañas de vidrio líquido en iOS, y un estilo de barra de pestañas difuminada en Android. Su router de Next.js mantiene el estado de la ruta; el plugin posee el navegador nativo.
@capgo/capacitor-transiciones --- transiciones de página estilo Ionic y retroceso de arrastre en iOS en la capa de WebView, sin adoptar la interfaz de usuario de Ionic.

Instale ambos:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Configure 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 concha de 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-pagey cap-contenty llame a setDirection('forward') o setDirection('back') contexto: fragmento de texto HTML de una cadena de UI de Capgo más larga (clave de padre `alternatives_cta_questions`). Página/área: página de comparación de alternativas de Capacitor live-update. Rol: párrafo de marketing o legal largo. Visto en: página alternatives.astro. Preservar términos de producto y marca de Capgo y términos de desarrollador exactamente. Clave de mensaje `alternatives_cta_questions` (Preguntas de Acción de Alternativas). | Fragmento de texto HTML de una cadena de UI de Capgo más larga (clave de padre `appflow_cta_questions`). Página/área: copia de marketing de comparación/migración de Appflow. Rol: párrafo de marketing o legal largo. Visto en: página ionic-appflow.astro. Preservar términos de producto y marca de Capgo y términos de desarrollador exactamente. Clave de mensaje `appflow_cta_questions` (Preguntas de Acción de Appflow). | Fragmento de texto HTML de una cadena de UI de Capgo más larga (clave de padre `capwesome_cta_questions`). Página/área: página de comparación de Capawesome. Rol: párrafo de marketing o legal largo. Visto en: página capwesome.astro. Preservar términos de producto y marca de Capgo y términos de desarrollador exactamente. Clave de mensaje `capwesome_cta_questions` (Preguntas de Acción de Capwesome). | Fragmento de texto HTML de una cadena de UI de Capgo más larga (clave de padre `consulting_faq_subtitle`). Página/área: página de servicios de consultoría. Rol: subtítulo o etiqueta de sección. Visto en: página consulting.astro. Preservar términos de producto y marca de Capgo y términos de desarrollador exactamente. Clave de mensaje `consulting_faq_subtitle` (Subtítulo de Preguntas Frecuentes de Consultoría). | Página/área: copia de marketing de comparación/migración de Appflow. Rol: etiqueta de UI corta o elemento de navegación. Visto en: página ionic-appflow.astro, página ionic-enterprise-plugins.astro, página soluciones/ionic-enterprise-plugins.astro. Clave de mensaje `appflow_plugins_or` (Appflow Plugins O). router.push() o router.back(). No se deben duplicar los encabezados o pie de página web cuando la navegación nativa controla esas superficies.

Vea las guías completas: Usando @capgo/capacitor-navigació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 compatibles con Capacitor:

bun add -D tailwind-capacitor

Inicio styles/globals.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Utiliza herramientas como pt-safe, pb-safe, y px-safe en lugar de agregarlos env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de Next.js, open a PR on GitHub.

Solucionando 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. Trabaja a través de estos controles en orden.

Asegúrate de que la etiqueta meta de viewport se aplique correctamente

Router de la Aplicación (app/exportar 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 el etiqueta de meta de viewport en pages/_app.tsx, no _document.tsx (Next.js puede no aplicar etiquetas de la forma que se espera para el comportamiento de la vista). _document.tsx Gestione el área segura de iOS desde un solo wrapper raíz

Cree un concha de aplicación única 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 wrappers 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-capacitorPuedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola caja.

Establece Capacitor iOS `contentInset` a `never` contexto: Página/área: Página de producto de actualizaciones en vivo. Rol: Etiqueta de IU corta o elemento de navegación. Clave de mensaje `live_update_dynamic_label_to` (Etiqueta dinámica de actualización en vivo a).

primero capacitor.config.tsEn contentInsetMode: 'css', prefiere el relleno nativo deshabilitado y deja que CSS (o la navegación nativa)

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-*) Mezclar el relleno de contenido automático de __CAPGO_KEEP_0__ con CSS

es una causa común de doble espaciado.

Encuentra el elemento que está desbordando en realidad 100vwTailwind w-screen, un ancho de píxel fijo, o un gran 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-screen, duplicado relleno de área segura, o un contenedor de ancho fijo — no del etiqueta meta de viewport en sí misma.

Optimización de rendimiento

Para asegurar un rendimiento óptimo de tu aplicación de 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 caché de vista web y 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 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
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, desbordamiento)
Agregó una interfaz de usuario que siente como nativa con Capgo Native Navigation y Transiciones

Pasos siguientes: (Credito de construcción nativa de Capgo)

Configuración Capgo para actualizaciones por aire sin la necesidad de volver a presentar la aplicación en la tienda
Agregar más plugins nativos como Cámara, Geolocalización o Notificaciones de Pulsación
Configurar iconos de aplicación y pantallas de bienvenida para producción
Preparar su aplicación para la presentación en la tienda de App Store y Google Play

Iniciando un proyecto nuevo? Consulte Construyendo 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 navegación de vidrio líquido y navegador nativo
Capacitor 8 Documentación
@capgo/capacitor-transiciones — Transiciones de página que sienten como si fueran 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 mejores y más rápidas 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 y Android con Capacitor 8 para planificar el trabajo de plugin nativo, conecte con Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, 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.

Convierta su aplicación web de Next.js en aplicaciones móviles nativas de iOS y Android con Capacitor 8