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

Introducción

Tiene una aplicación web Nuxt 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 la cámara, el sistema de archivos y las notificaciones push, mientras que mantiene tu código de Vue existente. A diferencia de Flutter o React Native, no necesitas reescribir nada — tu Nuxt code se ejecuta tal cual.

¿Qué aprenderás:

• Configura tu aplicación Nuxt existente para la generació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 sienta como si fuera nativa con Capgo Native Navigation y Transiciones

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

Ventajas de usar Nuxt y Capacitor

• Code Reutilización: Comparte tus componentes y lógica Vue entre aplicaciones web y móviles.
• Rendimiento: La generación estática de Nuxt crea paquetes optimizados perfectos para móviles.
• Nativas Capabilities: Accede a características de dispositivo como cámara, geolocalización y sistema de archivos a través de Capacitor plugins.
• Desarrollo Simplificado: Utiliza patrones Vue/Nuxt familiares sin aprender desarrollo nativo.

Requisitos previos

: Antes de comenzar, asegúrate de tener:

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

Configurando 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úrese de que su package.json contexto: texto fragmento de HTML 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: 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: Importante: Si está utilizando características del lado del servidor (API rutas, middleware del servidor, etc.), necesitará refactorizar esas características 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 plugins de Capacitor comunes 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/teclado: Controla el comportamiento del teclado en móviles
• @capacitor/pantalla-de-bienvenida: Administra la pantalla de bienvenida nativa
• @capacitor/barra-de-estado: Estiliza la barra de estado del dispositivo
• @capacitor/preferencias: Almacenamiento de valores clave (como localStorage pero nativo)

3. Inicializa Capacitor con los detalles de tu 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 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. Instale las plataformas nativas:

bun add @capacitor/ios @capacitor/android

6. Agregar 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 su proyecto que contienen los proyectos nativos.

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

7. Construya y sincronice su proyecto:

bun run mobile

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

Desarrollando y Desplegando Aplicaciones Nativas

To build and deploy your native mobile app, follow these steps:

Para desarrollar aplicaciones móviles nativas, sigue estos pasos: To develop iOS apps, you need to have Para desarrollar aplicaciones iOS, necesitas tener instalado Xcode Xcode

1. installed, and for Android apps, you need to have

instalado, y para aplicaciones Android, necesitas tener instalado

bun run mobile:ios

Android Studio

bun run mobile:android

Or directly with Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Moreover, if you plan to distribute your app on the app store, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android.

• In 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, 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, 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 instantáneamente en su dispositivo móvil. Para habilitar esta característica, 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

  Mire la dirección IPv4 en la salida.

2. Actualice su capacitor.config.ts a punto 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 la dirección IP local de su equipo (por ejemplo, 192.168.1.100).

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

4. Inicie su servidor de desarrollo de Nuxt y reconstruya en Xcode/Android Studio:

bun run dev

Ahora, cada vez que realice 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 realiza cambios en archivos nativos, deberá reconstruir el proyecto nativo ya que la recarga en vivo solo se aplica a cambios en el code web.

Usando Capacitor Plugins

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

1. Instala 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. Sincroniza los cambios con el proyecto nativo:

bun run mobile

O 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!', se mostrará el diálogo de compartir nativo.

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

Interfaz de usuario que se siente nativa con Capgo Navegación y Transiciones Nativas

He trabajado durante años con Para aplicaciones de escritorio nativas en móviles, pero integrarla con Nuxt es engorrosa y raramente vale la pena cuando ya tienes Para un sentir móvil nativo en una aplicación Nuxt + __CAPGO_KEEP_0__, utilice plugins __CAPGO_KEEP_1__ en lugar de kits de interfaz de usuario web como Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navegación-nativa.

For a native mobile feel in a Nuxt + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

• @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.
• @capgo/capacitor-transitions Configure la navegación nativa con modo de inserción de CSS para que el contenido web respete las barras nativas:

Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propiedad del sistema; Android utiliza un fondo difuminado de WebView):

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

Agregue transiciones de página nativas en su capa de aplicación:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Instale ambos:

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}`);
});

Para aplicaciones de escritorio nativas en móviles, pero integrarla con Nuxt es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS

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

Envuelve páginas de navegación en cap-router-outlet, cap-page, y cap-content, y llama setDirection('forward') o setDirection('back') antes de navegar. No duplique encabezados o pie de página web cuando la navegación nativa controla esas superficies.

Consulte las guías completas: 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). Ofrece safe-areas utilidades y otros plugins de Tailwind compatibles 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 agregarlas env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para su configuración de Nuxt, abre una solicitud de extracción en GitHub.

Corrigiendo problemas de diseño en iOS (Viewport, Área Segura y Desbordamiento Horizontal)

Si el contenido parece recortado, desplazado o desplazable horizontalmente en iOS, agregue más overflow-x: hidden o bien ajustando la etiqueta de viewport en sí, usualmente no se resuelve el problema. Trabaja a través de estas comprobaciones en orden.

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

En nuxt.config.ts, establece la vista a través de app.head:

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

Administra el área segura de iOS desde un solo wrapper raíz.

Crear una sola caja 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 wrappers de diseño a menudo hace que la interfaz de usuario se vea recortada o demasiado grande.

Con @capgo/tailwind-capacitorpuedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola caja.

Establecer Capacitor iOS contentInset hasta never primero

En capacitor.config.ts, prefiere el área de inserción nativa deshabilitada y deja que CSS (o la navegación nativa) se encargue del área segura: contentInsetMode: 'css'Mezclar el área de contenido automática 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 en realidad

El culpable habitual es un elemento que utiliza

, Tailwind 100vw, un ancho de píxeles fijo, o un tamaño w-screengran 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 rebosamiento horizontal provienen de 100vw / w-screenduplicado relleno de área segura, o un contenedor de ancho fijo — no del etiqueta meta de viewport en sí.

Conclusión

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

Lo que has logrado:

• Configuraste Nuxt para la generación estática
• Agregaste Capacitor 8 con plugins esenciales
• Construyó y desplegó a simuladores de iOS y Android
• Habilitó la recarga en vivo para el desarrollo
• Resolvió problemas de diseño iOS comunes (viewport, zona segura, rebosamiento)
• Agregó una interfaz de usuario que siente como una aplicación nativa con Capgo Navegación y Transiciones nativas

Próximos pasos:

• 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 Pila
• 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 y Google Play

Empezando un proyecto completamente nuevo? 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 Documentación
• @capgo/capacitor-navegación nativa — Barra de pestañas de vidrio líquido y navegador nativo
• @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 mejor y más rápido, regístrate para una cuenta gratuita actualmente.

Keep going from Convert Your Nuxt App to iOS & Android with Capacitor 8

Si estás utilizando Convert Your Nuxt App to iOS & Android with 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 Plugins de Capacitor por Capgo para el detalle de implementación en Plugins de Capacitor 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 Ionic Enterprise Plugin Alternatives, y Capgo Construcción Nativa para el flujo de trabajo del producto en Capgo Construcción Nativa.