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

Introducción

Tenga una aplicación web de 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 que mantiene tu código React existente. A diferencia de React Native, no necesitas reescribir nada — tu Next.js code se ejecuta tal cual.

¿Qué aprenderás:

Configura tu aplicación Next.js existente para exportación estática
Agrega Capacitor 8 con plugins nativos esenciales
Construye y prueba en simuladores de iOS y Android
Habilita la recarga en vivo para un desarrollo más rápido
Corrige problemas de diseño comunes de iOS (viewport, área segura, desbordamiento horizontal)
Agrega una interfaz de usuario que se siente 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

Reutilización de Code : Next.js te permite escribir componentes reutilizables y compartir code entre tus aplicaciones web y móviles, ahorrando tiempo y esfuerzo en el desarrollo.
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.
Página/área: Sección de problemas y soluciones de la página principal. Papel: Título de sección o página. Visto en: página premium-support.astro. Clave de mensaje `ps_help_performance_title` (Ps Ayuda Título de Rendimiento). : Next.js ofrece optimizaciones de rendimiento integradas, como renderizado en servidor y Capacitor de código, garantizando tiempos de carga rápidos y una experiencia de usuario suave.
Naturaleza nativa : Capacitor proporciona 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 características.

Desarrollo simplificado

: Con __CAPGO_KEEP_0__, 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 Next.js 15+ aplicación
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 requiere archivos HTML/JS/CSS estáticos para empaquetar en la aplicación nativa.

Abra su next.config.js (o next.config.ts)

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

archivo 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 refactorizarlas para utilizar alternativas de lado del cliente o APIs externas.

Agregar 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. Esto 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:

Instalar Capacitor core y CLI:

bun add @capacitor/core
bun add -D @capacitor/cli

Instalar plugins de Capacitor comunes que probablemente necesitarás:

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/keyboard: Controla el comportamiento del teclado en móviles
@capacitor/splash-screen: Administra la pantalla de bienvenida nativa
@capacitor/preferences: 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 su 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 su proyecto que contienen los proyectos nativos.

Para compilar el proyecto de Android, necesita Android Studio. Para iOS, necesita un Mac con Xcode.

Construye y sincroniza tu proyecto:

bun run mobile

Este 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, debes tener instalado el Xcode y para aplicaciones Android, debes tener instalado el Android Studio . 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, 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 instantáneamente 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
```
On Windows, ejecuta:
```
ipconfig
```
Busque la dirección IPv4 en la salida.

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

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

Reconstruya y ejecute la aplicación en su dispositivo utilizando Android Studio o Xcode.

Ahora, cada vez que realice cambios en su aplicación de 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 de 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:

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 , utiliza 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__-transiciones

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

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

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

Agregar 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' });

Envolver páginas de rutas en cap-router-outlet, cap-pagey cap-contenty llamar setDirection('forward') o setDirection('back') antes de trabajar en una nueva característica. router.push() o router.back(). No duplique los encabezados o pie de página web cuando la navegación nativa se encarga de esas superficies.

Ver los guías completas: Usar @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 safe-areas Proporciona 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 solicitud de revisión 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 solucionarlo. Trabaja a través de estos controles en orden.

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

Router de Aplicación (app/exportar viewport de app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

Router de Páginas (pages/coloca la etiqueta meta de viewport en pages/_app.tsx, no _document.tsx Con (Next.js puede no aplicar etiquetas de la forma que esperas para el comportamiento de la vista). _document.tsx Gestione el área seguro de iOS desde un solo wrapper raíz.

Crear un solo contenedor de aplicación y aplicar allí el relleno del área seguro, 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 del área seguro en encabezados, modales y contenedores 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-capacitoren ese contenedor único. pt-safe pb-safe px-safe Establezca __CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` context `never` primero

En capacitor.config.ts, prefiere el diseño nativo deshabilitado y deja que CSS (o la navegación nativa) maneje el área segura: contentInsetMode: 'css'Mezclar el diseño de contenido automático de __CAPGO_KEEP_0__ con CSS de relleno es una causa común de espaciado doble.

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-*) El culpable habitual es un elemento que utiliza

, Tailwind

, un ancho de píxeles fijo, o un tamaño 100vwEn Safari Web Inspector, ejecuta: w-screenCon Tailwind, reemplaza 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,
  }));

Con Tailwind, reemplaza w-screen con w-full cuando sea posible. Muchos problemas de rebosamiento horizontal provienen de 100vw / w-screenduplicado relleno de zona segura, o un contenedor de ancho fijo — no del etiqueta meta de viewport en sí.

Optimización de Rendimiento

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

Minimiza el tamaño de la aplicación eliminando dependencias y recursos innecesarios.
Optimiza 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 para motores de búsqueda (SEO).
Utiliza las optimizaciones integradas de Capacitor, como caché de vista web y empaquetado de la aplicación.

Conclusión

Has convertido exitosamente tu aplicación web Next.js existente en aplicaciones nativas 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
Capacitor 8 con plugins esenciales agregados
Construyó y desplegó a los 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 Navegación y Transiciones Nativas

Pasos siguientes:

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, Ubicación Geográfica o Notificaciones de Pulsación
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 nuevo proyecto? 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-navegación nativa — barra de tablas 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 inscríbete en 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 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 Construcción Nativa para el flujo de trabajo del producto en Capgo Construcción Nativa.

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