Convierta su aplicación Nuxt a 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 cámara, sistema de archivos y notificaciones push mientras 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.

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 recarga en vivo para un desarrollo más rápido
Soluciona problemas de diseño comunes de iOS (viewport, área segura, rebosamiento horizontal)
Agrega UI con sensación nativa con Capgo de navegación y transiciones nativas

¿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: Comparta sus 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: Acceda a características de dispositivo como cámara, geolocalización y sistema de archivos a través de Capacitor plugins.
Desarrollo Simplificado: Utilice patrones Vue/Nuxt familiares sin aprender desarrollo nativo.

Requisitos previos

: Antes de comenzar, asegúrese 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)

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úrese de que su 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á 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:

Instala Capacitor core y CLI:

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

Instala los 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/keyboard: 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)

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

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;

Instale plataformas nativas:

bun add @capacitor/ios @capacitor/android

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

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.

Desarrollar y Desplegar Aplicaciones Nativas

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

Para desarrollar aplicaciones de iOS, necesitas tener Xcode instalado, y para aplicaciones de Android, necesitas tener Android Studio instalado. Además, si planeas distribuir tu aplicación en la tienda de aplicaciones, necesitas 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.

xcode-run

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 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
```
En Windows, ejecute:
```
ipconfig
```
Busque la dirección IPv4 en la salida.

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

Sustituye 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 folder web y los cambios de configuración al proyecto nativo sin actualizar el proyecto completo.

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

bun run dev

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

Usando Capacitor Plugins

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

Instala el plugin de Compartir:

bun add @capacitor/share

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>

Sincroniza los cambios con el proyecto nativo:

bun run mobile

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

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 en iOS que causan desbordamiento horizontal o áreas de seguridad recortadas.

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 en su lugar Capgo plugins en lugar de kits de interfaz de usuario web como Konsta UI:

@capgo/capacitor-navegación-nativa — barra de navegación nativa, Liquid Glass barra de pestañas en iOS, y un estilo de barra de pestañas difuminado 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 en 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 difuminado de la capa de WebView):

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 capa de concha de la 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>

Envuelve páginas de rutas 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, 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 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 pantalla, Área segura y desbordamiento horizontal)

Si el contenido parece recortado, desplazado o desplazable horizontalmente en iOS, agregar más overflow-x: hidden o bien ajustando la etiqueta de viewport sola no suele solucionar 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 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 wrapper raíz

Crea un solo contenedor de aplicación 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 wrappers 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 ese solo contenedor.

Establezca Capacitor iOS `contentInset` a `never` primero

En capacitor.config.ts, prefiera el área de seguridad nativa deshabilitada y deja que CSS (o la navegación nativa) tenga el control del área de seguridad: contentInsetMode: 'css'Mezclar el área de contenido automático 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-*) Encuentre el elemento que está desbordando en realidad

El culpable habitual es un elemento que utiliza

, Tailwind 100vw, una anchura de píxeles fija o un ancho muy grande w-screen, a fixed pixel width, or a large min-width.

En el Inspector de Safari, 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 existente de Nuxt en aplicaciones nativas de iOS y Android utilizando Capacitor 8. Ahora tu código de Vue 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 desarrollo
Resolvió problemas de diseño iOS comunes (viewport, zona segura, rebosamiento)
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 de aplicaciones
Agregar más plugins nativos como Cámara, Ubicación Geográfica o Notificaciones de Push
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 de Apple y Google Play

¿Está empezando un nuevo proyecto? Consulte Crear una aplicación móvil de Nuxt desde cero para un recorrido guiado.

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 con un sentimiento nativo
@capgo/tailwind-capacitor – Utilidades de área segura de Tailwind para Capacitor
Capgo - Actualizaciones en vivo para aplicaciones Capacitor

Descubre cómo Capgo puede ayudarte a construir aplicaciones mejoradas de manera más rápida regístrate para una cuenta gratuita hoy.

Sigue adelante desde Convertir tu aplicación Nuxt a iOS & Android con Capacitor 8

Si estás utilizando Convertir tu aplicación Nuxt a iOS & 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.