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

Introduction

¿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 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 base Vue existente. A diferencia de Flutter o React Native, no necesita reescribir nada — su 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
Corregir problemas de diseño comunes de iOS (viewport, área segura, rebosamiento horizontal)
Agregar interfaz de usuario que sienta como nativa con Capgo Navegación y Transiciones nativas

¿Buscas empezar un nuevo proyecto desde cero? Crear una aplicación móvil de Nuxt desde cero.

Ventajas de utilizar Nuxt y Capacitor

Code ReutilizaciónCompartir componentes y lógica de Vue entre aplicaciones web y móviles.
Rendimiento: La generación estática de Nuxt crea paquetes optimizados perfectos para móviles.
Capacidades nativas: Acceder a características de dispositivo como cámara, geolocalización y sistema de archivos a través de Capacitor plugins.
Desarrollo simplificado: Utilizar patrones Vue/Nuxt familiares sin aprender desarrollo nativo.

Requisitos previos

Antes de empezar, asegúrese de tener:

Node.js 18+ instalado
Una aplicación existente Nuxt 4 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. __CAPGO_KEEP_0__ necesita archivos HTML/JS/CSS estáticos para empaquetar en la aplicación nativa.

Capacitor

Asegúrate de que tu package.json tiene 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 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 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 dispositivos móviles
@capacitor/splash-screen: Administra la pantalla de bienvenida nativa
@capacitor/status-bar: Establece el estilo de la barra de estado del dispositivo
@capacitor/preferences: Almacenamiento de valores clave-valor (como localStorage pero nativo)

Inicia Capacitor con los detalles de tu proyecto:

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

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

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;

Instalar plataformas nativas:

bun add @capacitor/ios @capacitor/android

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.

Compila y sincroniza tu proyecto:

bun run mobile

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

Desarrollo y Despliegue de 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.

Abre los proyectos nativos:

Para iOS:

bun run mobile:ios

For 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, 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.

xcode-run

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:

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;

Sustituya 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

El comando copy 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

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

Nota: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.

Usando Capacitor Plugins

Capacitor plugins allow you to access native device features from your Nuxt app. Let’s explore how to use the Compartir plugin como ejemplo:

Instale el plugin Compartir:

bun add @capacitor/share

Crear o actualizar una página para usar 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>

Sincronice los cambios con el proyecto nativo:

bun run mobile

O sincronice sin reconstruir:

bunx cap sync

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.

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 sentimiento móvil nativo en una aplicación Nuxt + Capacitor , utilice los plugins Capgo 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 pestañas de vidrio líquido en iOS, y un estilo de barra de pestañas difuminado en Android. Su router de Nuxt mantiene el estado de la 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 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 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 degradado 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 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-page, y cap-content, y llame a setDirection('forward') o setDirection('back') antes de navegar. No duplique los encabezados o pies de página web cuando la navegación nativa posee 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). 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.

Use utilidades como pt-safe, pb-safe, y px-safe en lugar de esparcirlos por todo el lugar 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.

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

Crea un contenedor de concha de aplicación único 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 .app-shell. El relleno de área segura duplicado en encabezados, modales y contenedores de diseño de layout a menudo hace que la interfaz de usuario parezca recortada o demasiado grande.

With @capgo/tailwind-capacitor, puedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola consola.

Establece Capacitor iOS `contentInset` a `never` primero

In capacitor.config.ts, prefiere el relleno de área segura deshabilitado nativo y deja que CSS (o la navegación nativa ‘) contentInsetMode: 'css'propia se encargue del área segura:

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

Mezclar Capacitor’s automatic content inset con CSS env(safe-area-inset-*) relleno es una causa común de doble espaciado.

Encuentra el elemento que está desbordando realmente

El culpable habitual es un elemento que utiliza 100vwTailwind w-screen, una anchura de píxel fija, o un ancho min-width.

En 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, el relleno de área segura duplicado, o un contenedor de ancho fijo — no del meta de la etiqueta 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. Tu código de Vue ahora se ejecuta nativamente en dispositivos móviles con acceso a APIs de dispositivos.

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 recarga en vivo para desarrollo
Corregido problemas de diseño comunes de iOS (viewport, área segura, rebosamiento)
Agregado interfaz de usuario con sensación nativa con Capgo Navegación nativa y transiciones

Pasos siguientes:

Configuración Capgo para actualizaciones sin recargar la aplicación desde la tienda
Agregar más plugins nativos como Cámara, Ubicación geográfica o Notificaciones push
Configurar iconos de la aplicación y pantallas de bienvenida para producción
Prepáre 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 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 seguras 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 Builds Nativos para el flujo de trabajo del producto en Capgo Builds Nativos.