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

Introducción

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 mejor rendimiento y nuevas características.

Capacitor envuelve tu aplicación web en un contenedor nativo, te da acceso a APIs de dispositivo como cámara, sistema de archivos y notificaciones push mientras mantiene tu código de React existente. A diferencia de React Native, no necesitas reescribir nada — tu Next.js code se ejecuta tal cual.

Lo que aprenderás:

Configura tu aplicación Next.js existente para exportación estática
Agregar Capacitor 8 con plugins nativos esenciales
Desarrollar y probar en simuladores de iOS y Android
Habilitar recarga en vivo para un desarrollo más rápido
Solucionar problemas de diseño comunes de iOS (viewport, área segura, desbordamiento horizontal)
Agregar una interfaz de usuario que sienta como nativa con Capgo Native Navigation y Transiciones

¿Quieres empezar un nuevo proyecto desde cero? Consulta 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: Permite a Next.js que escribas componentes reutilizables y compartas code entre tus aplicaciones web y móviles, ahorrando tiempo y esfuerzo en el desarrollo.
Rendimiento: Next.js ofrece optimizaciones de rendimiento integradas, como renderizado en servidor y code de código, garantizando tiempos de carga rápidos y una experiencia de usuario suave.
Capacidades Nativas: 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.
Desarrollo Simplificado: 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.

Requisitos previos

Antes de comenzar, asegúrate de tener:

Node.js 18+ instalado
Una aplicación existente Next.js 15+ aplicación
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. 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;

The output: 'export' El ajuste le dice a Next.js que genere archivos HTML estáticos, y images: { unoptimized: true } omite 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.), necesitará refactorizar esas características para utilizar alternativas de lado del cliente o APIs externas.

Agregar 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. Esto 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 Capacitor comunes que probablemente necesitará:

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

Estos plugins proporcionan características esenciales:

@capacitor/app@__CAPGO_KEEP_0__/teclado
@capacitor/keyboard@__CAPGO_KEEP_0__/pantalla-de-inicio
@capacitor/splash-screen@__CAPGO_KEEP_0__/preferencias
@capacitor/preferencesIniciar __CAPGO_KEEP_0__ con detalles de tu proyecto:

Initialize Capacitor with your project details:

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

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

Crear o actualizar 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;

Instalar plataformas nativas:

bun add @capacitor/ios @capacitor/android

Agregar 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 de 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 iOS, necesitas tener instalado Xcode y para aplicaciones Android, necesitas tener instalado Android Studio . 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.

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, 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 el recarga en vivo para ver los cambios instantáneamente en su dispositivo móvil. Para habilitar esta característica, siga estos pasos:

Encuentre su dirección IP local:

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

Actualiza tu capacitor.config.ts para 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;

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

Aplica los cambios a tu proyecto nativo:

bunx cap copy

El copy comando copia el directorio 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 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 Compartir plugin 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:

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.

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

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 , usa capacitor plugins en lugar de kits de interfaz de usuario solo para web como Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
@capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

— transiciones de página estilo Ionic y retroceso de arrastre de iOS en la capa de WebView, sin adoptar la interfaz de usuario de Ionic. Instala 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',
  },
});

Renderiza una barra de pestañas de vidrio líquido (iOS utiliza la renderización propia del sistema; Android utiliza un fondo de vista previa 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}`);
});

Agrega transiciones de página nativas en la caja de tu aplicación:

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

initTransitions({ platform: 'auto' });

Envuelve las páginas de ruteo 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 los encabezados o pie de página web cuando la navegación nativa posee esas superficies.

Consultar las guías completas: Usando @capgo/capacitor-navegación-nativa And 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). Ofrece safe-areas utilidades y otros plugins de Tailwind amigables con Capacitor:

bun add -D tailwind-capacitor

In styles/globals.css:

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

Utilice utilidades como pt-safe, pb-safe, y px-safe en lugar de esparcir env(safe-area-inset-*) por mano. El proyecto está activamente desarrollado — si algo falta para tu configuración de Next.js, abre una PR en GitHub.

Corrección de 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. Trabaja a través de estas comprobaciones en orden.

Asegúrate 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',
};

Pages Router (pages/): coloca la etiqueta meta de viewport en pages/_app.tsx, no _document.tsx (Puede que Next.js no aplique 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 root.

Crear un solo concha de aplicación y aplicar 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);
}

Duplicar el relleno de área segura en encabezados, modales y envolturas de diseño a menudo hace que la IU se vea recortada o demasiado grande. .app-shellCon

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitoren esa sola concha. pt-safe pb-safe px-safe Establezca __CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` to `never` primero

En capacitor.config.ts, prefiere el área de inserción nativa deshabilitada y deja que CSS (o la navegación nativa) tenga el área de seguridad: contentInsetMode: 'css'Mezclar el área 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-*) Encuentra el elemento que está desbordando realmente

El culpable usual es un elemento que utiliza

, Tailwind 100vw, una anchura de píxeles fija, o una gran w-screenEn Safari Web Inspector, ejecuta: min-width.

Con Tailwind, reemplaza

[...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,
  }));

por w-screen con w-full cuando sea posible. Muchos problemas de rebosamiento horizontal provienen de 100vw / w-screenla duplicación de relleno de área segura, o un contenedor de ancho fijo — no del etiqueta de meta de viewport en sí misma.

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.
Utiliza 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 de motores de búsqueda (SEO).
Toma ventaja de las optimizaciones integradas de Capacitor , como la caché de vista web y la empaquetación de la aplicación.

Conclusión

Has convertido exitosamente tu aplicación web existente de Next.js en aplicaciones nativas de iOS y Android utilizando Capacitor 8. Tu código web ahora se ejecuta nativamente en dispositivos móviles con acceso a APIs de dispositivo.

Lo que lograste:

Configuró Next.js para exportación estática
Agregó Capacitor 8 con plugins esenciales
Diseñó y desplegó a simuladores iOS y Android
Habilitó la recarga en vivo para desarrollo
Corrigió problemas de diseño de iOS comunes (viewport, área segura, rebosamiento)
Agregó una interfaz de usuario que siente como una aplicación nativa con Capgo Navegación y Transiciones nativas

Pasos siguientes:

Configuración Capgo para actualizaciones sin recargar la aplicación sin necesidad de volver a subirla a la tienda de aplicaciones
Agregar más plugins nativos como Cámara, Geolocalización o Notificaciones Push
Configura íconos de la aplicación y pantallas de bienvenida para producción
Prepara tu aplicación para la presentación en App Store y Google Play

¿Estás empezando un proyecto nuevo? Revisa 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-native-navigation — barra de pestañas de vidrio líquido y navegador nativo
Capacitor 8 Documentation
@capgo/capacitor-transitions — 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 Convertir tu aplicación Next.js a iOS & Android con Capacitor 8 para planificar el trabajo de plugin nativo, conecta con Directorio de plugins de Capgo para el flujo de trabajo del producto en Directorio de plugins de Capgo Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by 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 Next.js en iOS &amp; Android con Capacitor 8