Convierta su aplicación de Nuxt en iOS y Android con Capacitor 8

Introducción

Tienes una aplicación web Nuxt 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 Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.

¿Qué aprenderás:

• Configura tu aplicación Nuxt existente para generació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 Nuxt desde cero.

Benefits of Using Nuxt and Capacitor

• Code Reusability: 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 de dispositivos como cámara, geolocalización y sistema de archivos a través de plugins de Capacitor.Desarrollo simplificado

: Utiliza patrones Vue/Nuxt familiares sin aprender desarrollo nativo.

Antes de empezar, 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 (solo para desarrollo de Android)

Configuración de su aplicación Nuxt para móviles

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

Asegúrate de que package.json tenga el script de generación:

{
  "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"
  }
}

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

Prueba la generación estática ejecutando:

bun run generate

Deberías ver un .output/public carpeta con tus archivos estáticos. Esto es lo que Capacitor empaquetará en tu aplicación nativa.

Agregar Capacitor 8 a Tu Proyecto

Para empaquetar tu aplicación Nuxt en un contenedor móvil nativo, sigue estos pasos:

1. Instala Capacitor core y CLI:

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

2. Instala los plugins comunes de Capacitor que probablemente necesitarás:

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/keyboard: Controla el comportamiento del teclado en móviles
• @capacitor/splash-screen: Gestiona la pantalla de bienvenida nativa
• @capacitor/status-bar: Establece el estilo de la barra de estado del dispositivo
• @capacitor/preferences: Almacenamiento de valores clave (como localStorage pero nativo)

3. Inicializa Capacitor con detalles de tu proyecto:

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

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

4. 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: '.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. Instalar plataformas nativas:

bun add @capacitor/ios @capacitor/android

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

7. Construye y sincroniza tu proyecto:

bun run mobile

Esto ejecuta tu script personalizado que genera la compilación estática de Nuxt y sincroniza los archivos 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 iOS, debes tener Xcode instalado, y para aplicaciones 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. Abre los proyectos nativos:

Para iOS:

bun run mobile:ios

Foro Android:

bun run mobile:android

O directamente con Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Construye y ejecuta la aplicación:

• 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 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, puedes aprovechar la recompilación en vivo para ver cambios instantáneos en tu dispositivo móvil. Para habilitar esta característica, sigue estos pasos:

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

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

export default config;

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

3. Aplica los cambios a tu 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.

4. Inicia tu servidor de desarrollo Nuxt y reconstruye en Xcode/Android Studio:

bun run dev

Now, every time you make changes to your Nuxt app, the mobile app will automatically reload to reflect those changes.

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 en el web code.

Usando Capacitor Plugins

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

1. Instale el plugin de Compartir:

bun add @capacitor/share

2. Crear o actualizar una página para utilizar el plugin de Compartir. En Nuxt 4, las páginas se encuentran 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 sincronice sin reconstruir:

bunx cap sync

4. Reconstruya y ejecute la aplicación en su dispositivo.

Now, when you click the “Compartir ahora!” button, the native share dialog will appear.

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.

UI nativo con Capgo navegación nativa y transiciones

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

Para un sentir móvil nativo en una aplicación Nuxt + Capacitor, utilice plugins Capgo en lugar de kits UI web únicamente como Konsta UI:

• @capgo/capacitor-navegación-nativa — barra de navegación nativa, barra de pestañas de vidrio líquido en iOS, y un estilo de barra de pestañas empañada en Android. Su router Nuxt mantiene el estado de ruta; el plugin posee el navegador nativo.
• @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso de arrastre de 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

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 su concha de 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 rutas en cap-router-outlet, cap-pagey cap-contenty llame a setDirection('forward') o setDirection('back') context: Fragmento de texto HTML de una cadena de Capgo UI más larga (clave de padre `alternatives_cta_questions`). Página/área: Comparación de alternativas de actualización en vivo de Capacitor. 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 CTA de alternativas). | Fragmento de texto HTML de una cadena de Capgo UI 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 CTA de Appflow). | Fragmento de texto HTML de una cadena de Capgo UI más larga (clave de padre `capwesome_cta_questions`). Página/área: 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 CTA de Capwesome). | Fragmento de texto HTML de una cadena de Capgo UI más larga (clave de padre `consulting_faq_subtitle`). Página/área: Página de servicios de consultoría. Rol: Título de sección o etiqueta. 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` (Título de subtítulo de FAQ 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).

antes de navegar. No duplique los encabezados o pie de página web cuando la navegación nativa propietaria se encarga de esas superficies. Using @capgo/capacitor-native-navigation Usando @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation 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 amigables con Capacitor:

bun add -D tailwind-capacitor

In 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-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 Nuxt, 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 usualmente no lo resuelve. Trabaja a través de estos controles en orden.

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

In nuxt.config.ts, establece el viewport a través de app.head:

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

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

Crear un solo contenedor de aplicación y aplicar allí el relleno de área segura — no en múltiples componentes anidados:

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-shellEl relleno de área segura duplicado en encabezados, modales y contenedores de diseño a menudo hace que la interfaz de usuario parezca recortada o demasiado grande.

With @capgo/tailwind-capacitorcon utilities como pt-safe pb-safe px-safe en esa sola caja.

Establece Capacitor iOS contentInset para never context: Página/área: Página de producto 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 dinámica de actualización en vivo para).

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 __CAPGO_KEEP_0__’s automatic content inset con CSS

Encuentra el elemento que se desborda realmente

El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screen, una anchura de píxel fija, 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 etiqueta meta de viewport en sí misma.

Conclusión

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

Lo que has logrado:

• Configurado Nuxt para generación estática
• Agregado Capacitor 8 con plugins esenciales
• Construido y desplegado a simuladores iOS y Android
• Habilitado el recarga en vivo para desarrollo
• Corregido problemas de diseño comunes de iOS (viewport, área segura, rebosamiento)
• Agregado interfaz de usuario que siente como nativa con Capgo Navegación y Transiciones Nativas

Pasos siguientes:

• Configuración Capgo para actualizaciones sin tienda de aplicaciones
• 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
• Prepárate para la presentación de tu aplicación en App Store y Google Play

¿Estás empezando un nuevo proyecto? Revisa 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 — @Capgo/transiciones
• @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 Nuxt a iOS y Android con Capacitor 8

Si estás utilizando Convertir tu aplicación Nuxt 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 Alternativas de Plugins de Ionic Enterprise, y Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas