Convert Your Nuxt App to iOS & Android with Capacitor 8

Introducción

Tiene una aplicación web Nuxt 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 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 de base Vue existente. A diferencia de Flutter o React Native, no necesita reescribir nada — su aplicación Nuxt code se ejecuta tal cual.

¿Qué aprenderá:

• Configure su aplicación Nuxt existente para generació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
• Resolver problemas de diseño comunes en iOS (viewport, área segura, rebosamiento horizontal)
• Agregar una interfaz de usuario que se sienta nativa con Capgo Navegación nativa y transiciones

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

Ventajas de utilizar Nuxt y Capacitor

• Code Reutilización: Comparte tus componentes Vue y lógica entre aplicaciones web y móviles.
• Rendimientocontexto: Página/área: Sección de problemas/soluciones de la página principal. Rol: Título de sección o página. Visto en: página premium-support.astro. Clave de mensaje `ps_help_performance_title` (Ps Ayuda Rendimiento Titulo).
• : La generación estática de Nuxt crea paquetes optimizados perfectos para móviles.: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
• : Accede a características del dispositivo como cámara, geolocalización y sistema de archivos a través de __CAPGO_KEEP_0__ plugins.: Utilice patrones familiares de Vue/Nuxt sin aprender desarrollo nativo.

Requisitos previos

Antes de comenzar, asegúrese de tener:

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

Configurando su aplicación Nuxt para móvil

The first step is to configure your Nuxt app for static generation. Capacitor needs static HTML/JS/CSS files to bundle into the native app.

Verifique que su package.json contexto: HTML fragmento de texto de una cadena de UI de Capgo (clave de página `solutions_cordova_to_capacitor_ai_step2_body`). Página/área: página de marketing de soluciones de Capgo. Rol: oración de copia de sitio web. Visto en: página solutions/cordova-to-capacitor-ai.astro. Clave de mensaje `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body).

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

tiene el script de generación: If you’re using server-side features (API routes, server middleware, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Si está utilizando características del lado del servidor (__CAPGO_KEEP_0__ rutas, middleware del servidor, etc.), necesitará refactorizarlas para utilizar alternativas del lado del cliente o APIs externas.

bun run generate

Pruebe la generación estática ejecutando: .output/public folder with your static files. This is what Capacitor will bundle into your native app.

carpeta con sus archivos estáticos. Esto es lo que Capacitor empaquetará en su aplicación nativa.

Agregar __CAPGO_KEEP_0__ 8 a su proyecto

1. Para empaquetar su aplicación Nuxt en un contenedor móvil nativo, siga estos pasos: Instale Capacitor core y CLI:

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

2. Instale los plugins comunes Capacitor que probablemente necesitará:

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

Estos plugins proporcionan características esenciales:

• @capacitor/app: Maneja eventos de ciclo de vida de la aplicación (anterior/plano, enlaces profundos)
• @capacitor/teclado: Controla el comportamiento del teclado en móviles
• @capacitor/pantalla-de-inicio: Gestiona la pantalla de inicio nativa
• @capacitor/barra-de-estado: Estiliza la barra de estado del dispositivo
• @capacitor/preferencias: Almacenamiento de valores clave (como localStorage pero nativo)

3. Inicia Capacitor con tus detalles de proyecto:

bunx cap init my-app com.example.myapp --web-dir .output/public

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

4. Crea o actualiza el archivo capacitor.config.ts con la configuración adecuada:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

5. Instala las plataformas nativas:

bun add @capacitor/ios @capacitor/android

6. Agrega las carpetas de la 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 compilar el proyecto de Android, necesitas Android Studio. Para iOS, necesitas un Mac con Xcode.

7. Construye y sincroniza tu proyecto:

bun run mobile

Este ejecuta tu script personalizado que genera la compilación estática de Nuxt y sincroniza los archivos con las plataformas nativas.

Desarrollar Aplicaciones Nativas

Para construir y desplegar tu aplicación móvil nativa, sigue estos pasos:

Para desarrollar aplicaciones de iOS, debes tener Xcode instalado, y para aplicaciones de Android, debes 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.

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

2. 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 Nuxt 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 función, siga estos pasos:

1. 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 el resultado.

2. 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: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... your plugin config
  },
};

export default config;

Sustituya YOUR_IP_ADDRESS por su dirección IP local (por ejemplo, 192.168.1.100).

3. Aplicar los cambios a su proyecto nativo:

bunx cap copy

El copy copiar el comando copia el folder web y los cambios de configuración al proyecto nativo sin actualizar todo el proyecto.

4. Inicie su servidor de desarrollo de Nuxt y vuelva a compilar en Xcode/Android Studio:

bun run dev

Ahora, cada vez que haga cambios en su aplicación de Nuxt, la aplicación móvil se recargará automáticamente para reflejar esos cambios.

Nota: Si instala nuevos plugins o hace cambios en archivos nativos, necesitará volver a compilar el proyecto nativo ya que la recarga en vivo solo se aplica a cambios web code.

Usando Capacitor Plugins

Los plugins Capacitor permiten acceder a características de dispositivos nativos desde su aplicación de Nuxt. Exploraremos cómo utilizar el plugin Compartir como ejemplo:

1. Instale el plugin Compartir:

bun add @capacitor/share

2. Crear o actualizar una página para utilizar el plugin Compartir. En Nuxt 4, las páginas van en app/pages/:

<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
    <button
      @click="shareContent"
      class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
    >
      Share now!
    </button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function shareContent() {
  await Share.share({
    title: 'Check this out!',
    text: 'Built with Nuxt and Capacitor',
    url: 'https://capacitorjs.com',
    dialogTitle: 'Share with friends',
  });
}
</script>

3. Sincronice los cambios con el proyecto nativo:

bun run mobile

O simplemente sincroniza sin reconstruir:

bunx cap sync

4. Reconstruye y ejecuta la aplicación en tu dispositivo.

Ahora, cuando hagas clic en el botón “Compartir ahora!”, aparecerá el diálogo de compartir nativo.

Enseguida, puedes hacer que la aplicación se sienta más nativa en iOS y Android con Capgo navegación y transiciones, y solucionar problemas de diseño comunes de iOS que causan desbordamiento horizontal o áreas de seguridad recortadas.

Interfaz de usuario con un sentimiento nativo con Capgo Navegación y Transiciones Nativas

He trabajado durante años con Ionic para construir aplicaciones de múltiples plataformas, pero integrarla con Nuxt es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS.

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

• @capgo/capacitor-navegación-nativa — barra de navegación nativa, barra de tablas de vidrio líquido en iOS, y un estilo de barra de tablas empañado en Android. Tu router de Nuxt mantiene el estado de ruta; el plugin posee el navegador nativo.
• @capgo/capacitor-transiciones — Transiciones de página de estilo Ionic y retroceso de borde de 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 de fondo de WebView difuminado):

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 la caja de su aplicación:

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';

initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
  }
});

const openSettings = () => {
  setDirection('forward');
  router.push('/settings');
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <router-view />
  </cap-router-outlet>
</template>

Envuelva las páginas de ruteo en cap-router-outlet, cap-pagey cap-contentllame a setDirection('forward') o setDirection('back') Page/area: Página de comparación de alternativas de actualización en vivo de Capacitor. Role: Párrafo de marketing o legal largo. Seen in: página alternatives.astro. Preservar términos de producto y marca de Capgo exactamente. Message key `alternatives_cta_questions` (Preguntas de llamada a la acción de alternativas). | Página/área: Copia de marketing de comparación/migración de Appflow. Role: Párrafo de marketing o legal largo. Seen in: página ionic-appflow.astro. Preservar términos de producto y marca de Capgo exactamente. Message key `appflow_cta_questions` (Preguntas de llamada a la acción de Appflow). | Página/área: Página de comparación de Capawesome. Role: Párrafo de marketing o legal largo. Seen in: página capwesome.astro. Preservar términos de producto y marca de Capgo exactamente. Message key `capwesome_cta_questions` (Preguntas de llamada a la acción de Capwesome). | Página/área: Página de servicios de consultoría. Role: Título de sección o etiqueta. Seen in: página consulting.astro. Preservar términos de producto y marca de Capgo exactamente. Message key `consulting_faq_subtitle` (Título de sección de preguntas frecuentes de consultoría). | Página/área: Copia de marketing de comparación/migración de Appflow. Role: Etiqueta de UI corta o elemento de navegación. Seen in: página ionic-appflow.astro, página ionic-enterprise-plugins.astro, página soluciones/ionic-enterprise-plugins.astro. Message key `appflow_plugins_or` (Appflow Plugins Or).

antes de navegar. No duplique los encabezados o pie de página web cuando la navegación nativa propietaria se encarga de esas superficies. Usando @capgo/capacitor-navegación nativa y Usando @capgo/capacitor-transiciones.

Áreas seguras con Tailwind

Para áreas seguras del dispositivo 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-capacitor

En app/assets/css/main.css:

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

Para Nuxt 4 con Tailwind CSS 4, mantenga esta importación en el archivo CSS referenciado desde nuxt.config.ts.

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

Corrigiendo 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 usualmente no lo resuelve. Trabaja a través de estas comprobaciones en orden.

Asegúrate de que la etiqueta meta de viewport esté aplicada correctamente

In nuxt.config.tsen app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

Configura el viewport a través de

Gestiona el área segura de iOS desde un solo contenedor raíz solo

html,
body,
#__nuxt {
  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);
}

Envuelve todo el contenido de la página dentro de .app-shell . La duplicación de la zona de seguridad en encabezados, modales y contenedores de diseño a menudo hace que la interfaz de usuario se vea 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 contexto: Página/área: Página de productos de actualizaciones en vivo. Rol: Etiqueta de interfaz de usuario corta o elemento de navegación. Clave de mensaje `live_update_dynamic_label_to` (Etiqueta de actualización en vivo dinámica a).

primero capacitor.config.tsIn contentInsetMode: 'css', prefiere el deshabilitado de la zona de inserción nativa y deja que CSS (o la navegación nativa ')

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

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

Encuentra el elemento que está desbordando realmente

El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screen, un ancho de píxel fijo, o un contenedor muy ancho min-width.

In 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 viewport en sí.

Conclusión

Has convertido con éxito su aplicación web Nuxt existente en aplicaciones móviles nativas iOS y Android utilizando Capacitor 8. Ahora su código Vue se ejecuta nativamente en dispositivos móviles con acceso a APIs de dispositivo.

Lo que ha logrado:

• Configuró Nuxt para la generació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 una aplicación nativa con Capgo Native Navigation y Transiciones

Pasos siguientes:

• Configuración Capgo para actualizaciones por aire sin la necesidad de volver a presentar la aplicación en la tienda de aplicaciones
• Agregar más plugins nativos como Cámara, Ubicación Geográfica 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 App Store y Google Play

¿Está empezando un nuevo proyecto? Consulte Crear una aplicación móvil de Nuxt desde cero para una guía paso a paso.

Recursos

• Documentación de Nuxt
• Capacitor 8 Documentation
• @capgo/capacitor-native-navigation — Barra de navegación de vidrio líquido y navegador nativo
• @capgo/capacitor-transitions — transiciones de página con un sentimiento nativo
• @capgo/tailwind-capacitor — utilidades de área seguras de Tailwind para Capacitor
• Capgo - Actualizaciones en vivo para aplicaciones Capacitor

Aprende cómo Capgo puede ayudarte a crear aplicaciones mejores y más rápidas inscríbete en una cuenta gratuita hoy.

Sigue adelante desde Convertir tu aplicación Nuxt en iOS y Android con Capacitor 8

Si estás utilizando Convertir tu aplicación Nuxt en iOS y Android con Capacitor 8 para planificar el trabajo de plugin nativo, conecta con Directorio de plugin de Capgo para el flujo de trabajo del producto en el directorio de Capgo 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.