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

Introducción

Tienes una aplicación web de Nuxt existente? En este guía, aprenderás 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 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 de Nuxt existente para generación estática
• Agrega Capacitor 8 con plugins nativos esenciales
• Construye y prueba en simuladores de iOS y Android
• Activar actualización en vivo para un desarrollo más rápido
• Corregir problemas de diseño comunes de iOS (viewport, área segura, rebosamiento horizontal)
• Agregar una interfaz de usuario que se sienta nativa con Capgo Navegación nativa y transiciones

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

Ventajas de usar Nuxt y Capacitor

• Code Reutilización: Compartir tus componentes Vue y lógica entre aplicaciones web y móviles.
• Rendimiento:Nuxt crea bundles estáticos optimizados perfectos para móviles.
• Capacidades NativasAcceda a características del dispositivo como cámara, geolocalización y sistema de archivos a través de plugins Capacitor.
• Desarrollo Simplificado: Utiliza patrones Vue/Nuxt familiares sin aprender desarrollo nativo.

Requisitos previos

Antes de empezar, asegúrate de tener:

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

Configurando su aplicación Nuxt para móvil

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

Important: 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.

Pruebe 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 su proyecto

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

1. Instale el núcleo Capacitor y CLI:

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

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

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

Estos plugins proporcionan características esenciales:

• @capacitor/appGestione eventos de ciclo de aplicación (anterior/plano, enlaces profundos)
• @capacitor/teclado: Controlar el comportamiento del teclado en móviles
• @capacitor/pantalla-de-inicio: Gestione la pantalla de inicio nativa
• @capacitor/barra-de-estado: Estile la barra de estado del dispositivo
• @capacitor/preferencias: Almacenamiento de valores clave (como localStorage pero nativo)

3. Inicia Capacitor con tus detalles de 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).

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. Instala plataformas nativas:

bun add @capacitor/ios @capacitor/android

6. Agrega las 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 StudioPara 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, necesitas tener Xcode instalado, y para aplicaciones Android, necesitas 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

Para 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 exitosamente tu aplicación web de Nuxt en un dispositivo móvil.

Pero espera, hay una forma aún más rápida de hacer esto durante el desarrollo…

Capacitor Recarga en vivo

Durante el desarrollo, puedes aprovechar la recompilación en vivo para ver los cambios instantáneamente en tu dispositivo móvil. Para habilitar esta función, 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 con tu dirección IP local (por ejemplo, 192.168.1.100).

3. Aplica los cambios a tu proyecto nativo:

bunx cap copy

El copy La orden copia el carpeta web y los cambios de configuración al proyecto nativo sin actualizar el proyecto completo.

4. Inicia tu servidor de desarrollo de Nuxt y reconstruye 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 web code.

Usando Capacitor Plugins

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

1. Instale el plugin Compartir:

bun add @capacitor/share

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

3. Sincronice los cambios con el proyecto nativo:

bun run mobile

O simplemente sincronice 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 navegación y transiciones Capgo y solucionar problemas de diseño comunes de iOS que causan rebosamiento horizontal o áreas de seguridad recortadas.

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

Han trabajado durante años con Ionic para construir aplicaciones de múltiples plataformas, pero integrarla con Nuxt es engorrosa 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 de interfaz de usuario web solo como Konsta UI:

• @capgo/capacitor-navegación-nativa – barra de navegación nativa, Liquid Glass de pestaña de tab bar en iOS, y un estilo de pestaña de fondo 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 por swipe 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 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',
  },
});

Render un tablero de Liquid Glass (iOS utiliza la renderización propia del sistema; Android utiliza un fondo difuminado 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 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 ruta en cap-router-outlet, cap-pagey cap-contenty llame a 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.

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

Utilice herramientas 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 tu configuración de Nuxt, abrir una PR en GitHub.

Resolviendo 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 solucionarlo. Trabaja a través de estos controles en orden.

Asegúrate de que la etiqueta meta de viewport esté aplicada 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 contenedor raíz

Crear una caja de aplicación única y aplicar relleno de área segura allí — no en componentes anidados múltiples:

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 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 caja única.

Establecer Capacitor iOS contentInset en never first

primero capacitor.config.ts, prefiera el diseño nativo deshabilitado y deja CSS (o la navegación nativa) contentInsetMode: 'css'Propietario del área segura:

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

Mezclar Capacitor’s contenido automático de ajuste con CSS env(safe-area-inset-*) el relleno de padding es una causa común de doble espaciado.

Encuentre el elemento que sobresale

El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screenuna anchura de píxel fija, o una gran 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 desbordamiento horizontal provienen de 100vw / w-screen, relleno de área segura duplicado, o un contenedor de ancho fijo — no de la etiqueta meta de viewport en sí misma.

Conclusión

Has convertido exitosamente tu aplicación web Nuxt existente en aplicaciones móviles nativas iOS y Android utilizando Capacitor 8. Ahora tu código Vue 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
• Compilado y desplegado a simuladores iOS y Android
• Habilitado live reload para desarrollo
• Corregido problemas de diseño comunes de iOS (viewport, área segura, rebosamiento)
• Agregado interfaz de usuario que siente como nativa con Capgo Native Navigation y Transiciones

Pasos siguientes:

• Configura Capgo para actualizaciones por aire sin reenvío a la tienda de aplicaciones
• Agregar más plugins nativos como Cámara, Ubicación Geográfica o Notificaciones de Pus.
• Configura íconos 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 navegación 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 - Live Updates for Capacitor Apps

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 en iOS & Android con Capacitor 8

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