Convert Your Nuxt App to iOS & Android with Capacitor 8

Introducción

Tiene una aplicación web de Nuxt existente? En esta guía, aprenderá a transformarla en aplicaciones móviles nativas de iOS y Android utilizando Capacitor Convierta su aplicación de Nuxt en aplicaciones móviles nativas de iOS y Android con Capgo 8

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 de Vue existente. A diferencia de Flutter o React Native, no necesitas reescribir nada — tu Nuxt code se ejecuta tal como está.

Lo que aprenderás:

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

Ventajas de usar Nuxt y Capacitor

• Code Reutilización: Comparte tus componentes Vue y lógica entre aplicaciones web y móviles.
• Rendimiento: La generación estática de Nuxt crea paquetes optimizados perfectos para móviles.
• Capacidades Nativas: 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.

Verifique que su package.json contexto

{
  "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á 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 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/teclado: Controla el comportamiento del teclado en móviles
• @capacitor/pantalla-de-inicio: Administra 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. 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 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 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: Xcode Xcode Para desarrollar aplicaciones de Android, necesitas tener Android Studio

1. Android Studio

instalado. Además, si planeas distribuir tu aplicación en la tienda de aplicaciones, necesitarás inscribirte en el programa de desarrolladores de Apple para iOS y en el Google Play Console para Android.

bun run mobile:ios

Abre los proyectos nativos:

bun run mobile:android

Or directly with Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Para 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 el live reloading 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

  Busque la dirección IPv4 en el resultado.

2. Actualice su capacitor.config.ts a la dirección de 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 vuelva a compilar 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á volver a compilar el proyecto nativo ya que la recarga en vivo solo se aplica a cambios en el web code.

Usando Capacitor Plugins

plugins de Capacitor te permiten acceder a características de dispositivos nativos desde tu aplicación 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 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 que se siente nativa con Capgo Navegación y Transiciones Nativas

He trabajado durante años con Para construir aplicaciones de múltiples plataformas, 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 en su lugar 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 la capa WebView en iOS, sin adoptar la interfaz de usuario de Ionic.
• @capgo/capacitor-transitions Configure la navegación nativa con el 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 propia del sistema; Android utiliza un fondo difuminado de la capa WebView):

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

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

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

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

Para construir aplicaciones de múltiples plataformas, pero integrarla con Nuxt es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS.

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 un sentir móvil nativo en una aplicación Nuxt + __CAPGO_KEEP_0__, utilice en su lugar plugins __CAPGO_KEEP_1__ en lugar de kits de interfaz de usuario web como Konsta UI: Ionic.

<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 de dispositivos en Tailwind CSS, utiliza @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 agregarlos 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.

Corrección de problemas de diseño de iOS (Vista de la página, Área seguro 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',
        },
      ],
    },
  },
});

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

Crea una caja de aplicación única y aplica 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 envolturas de diseño a menudo hace que la interfaz de usuario parezca recortada o demasiado grande.

Con @capgo/tailwind-capacitor, puedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa caja única.

Establecer Capacitor iOS contentInset hasta never primero

En capacitor.config.ts, prefiere el deshabilitado nativo y deja que CSS (o la navegación nativa) contentInsetMode: 'css') tenga el área segura:

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

Mezclar el contenido de Capacitor automatico con CSS env(safe-area-inset-*) es una causa común de doble espaciado.

Encuentra el elemento que está desbordando en realidad

El culpable usual es un elemento que utiliza 100vw, Tailwind w-screen, un ancho de píxeles fijo, o un tamaño grande 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 lograste:

• 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
• Resuelto problemas de diseño comunes de iOS (viewport, área segura, rebosamiento)
• Agregado UI con sensación nativa utilizando Capgo Navegación y Transiciones nativas

Pasos siguientes:

• Configuración Capgo para actualizaciones por aire sin resubmisión en la tienda de aplicaciones
• 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 Mac App Store y Google Play

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 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 mejores y más rápidas, 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 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 Ionic Enterprise Plugin Alternatives, y Capgo Construcción Nativa para el flujo de trabajo del producto en Capgo Construcción Nativa.