Crear Aplicaciones Móviles con Vue y Capacitor

En este tutorial, te guiamos a través del proceso de convertir una aplicación web de Vue en una aplicación móvil nativa utilizando Capacitor. También puedes agregar Capgo Navegación Nativa y Transiciones para un sentir móvil nativo, y utilizar tailwind-capacitor para áreas seguras.

Sobre Capacitor

Capacitor es una herramienta revolucionaria que te permite integrar fácilmente en cualquier proyecto web y convertir tu aplicación en una aplicación móvil nativa. Genera proyectos de Xcode y Android Studio nativos para ti y te proporciona acceso a características de dispositivos nativos como la cámara a través de un puente de JavaScript.

Preparando tu aplicación de Vue

Primero, crea una nueva aplicación de Vue ejecutando el siguiente comando:

vue create my-app
cd my-app
npm install

Para preparar tu aplicación de Vue para la implementación móvil nativa, necesitarás exportar tu proyecto. Agrega un script en tu archivo package.json para construir y copiar el proyecto de Vue:

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

Después de ejecutar el build comando, deberías ver un nuevo dist carpeta en el directorio raíz de tu proyecto. Esta carpeta se utilizará por Capacitor más adelante.

Agregar Capacitor a Tu Aplicación de Vue

Para convertir tu aplicación web de Vue en un contenedor móvil nativo, sigue estos pasos:

1. Instala el Capacitor CLI como dependencia de desarrollo y configúralo dentro de tu proyecto. Acepta los valores predeterminados para nombre y ID de paquete durante la configuración.

2. Instala el paquete principal y los paquetes relevantes para las plataformas iOS y Android.

3. Agrega las plataformas, y Capacitor creará carpetas para cada plataforma en la raíz de tu proyecto:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Vue project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

Deberías ver ahora nuevos iOS y android carpetas en tu proyecto Vue.

Actualice el archivo capacitor.config.json para que apunte el webDir a la salida de su comando de compilación:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

Now, you can build your Vue project and sync it with Capacitor:

npm run build
npx cap sync

__CAPGO_KEEP_0__: "Build and Deploy Native Apps"

Para desarrollar aplicaciones de iOS, necesitas instalar Xcode, y para aplicaciones de Android, necesitas instalar Android Studio. Además, debes inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android para distribuir tu aplicación en la tienda de aplicaciones.

Utiliza los Capacitor CLI para abrir ambos proyectos nativos:

npx cap open ios
npx cap open android

Despliega tu aplicación en un dispositivo conectado utilizando Android Studio o Xcode.

Capacitor Live Reload

Habilita la recarga en vivo en tu dispositivo móvil teniendo la aplicación Capacitor cargar el contenido desde una URL específica en tu red.

Encuentra tu dirección IP local y actualiza el capacitor.config.ts archivo con la dirección IP y el puerto correctos:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:8080',
    cleartext: true
  }
};

export default config;

Aplica estos cambios copiándolos a tu proyecto nativo:

npx cap copy

Ahora, tu aplicación se recargará automáticamente y mostrará cambios cuando actualices tu aplicación Vue.

Usando Capacitor Plugins

Instala un plugin Capacitor como el plugin de Compartir y úsalo en tu aplicación Vue:

npm i @capacitor/share

Importa el paquete y llama al share() función en tu aplicación:

<template>
  <div>
    <h1>Welcome to Vue and Capacitor!</h1>
    <button @click="share">Share now!</button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function share() {
  await Share.share({
    title: 'Open Youtube',
    text: 'Check new video on youtube',
    url: 'https://www.youtube.com',
    dialogTitle: 'Share with friends'
  });
}
</script>

Después de instalar nuevos plugins, ejecuta el sync comando y vuelve a desplegar la aplicación en tu dispositivo:

npx cap sync

A continuación, 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 rebosamiento 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 Ionic para construir aplicaciones de múltiples plataformas, pero integrarla con Vue es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS.

Para un sentir móvil nativo en una aplicación Vue + Capacitor , utiliza 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 barra de pestañas en iOS, y un estilo de barra de pestañas difuminado en Android. Tu router de Vue mantiene el estado de la ruta; el plugin es dueño del navegador nativo.
• @capgo/capacitor-transiciones — Transiciones de página estilo Ionic y retroceso de borde 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 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',
  },
});

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

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 pie de página web cuando la navegación nativa posee esas superficies. 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 src/assets/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Utilice utilidades como pt-safe, pb-safe, y px-safe en lugar de esparcir env(safe-area-inset-*) a mano. El proyecto está activamente desarrollado — si algo falta para tu configuración de Vue, abre una PR en GitHub.

Solucionar Problemas de Diseño de iOS (Viewport, Área Segura y Desbordamiento Horizontal)

Si el contenido parece recortado, desplazado o horizontalmente desplazable en iOS, agregar más overflow-x: hidden o ajustar la etiqueta de viewport sola no suele solucionarlo. Trabaja a través de estas comprobaciones en orden.

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

Agrega la etiqueta meta de viewport en index.html dentro <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 aplicación único y aplica allí el relleno de área segura — no en múltiples componentes anidados:

html,
body,
#app {
  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 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.

Establece Capacitor iOS contentInset a never primero

En capacitor.config.ts, prefiere el área de seguridad nativa deshabilitada 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: 'dist',
  ios: {
    contentInset: 'never',
  },
};

Mezclar Capacitor’s contenido de área de seguridad automático con CSS env(safe-area-inset-*) padding 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, un ancho de píxeles fijo, o un 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-screenduplicado, o un contenedor de ancho fijo — no del etiqueta meta de viewport en sí misma.

Conclusión

Capacitor es una gran opción para crear aplicaciones nativas basadas en un proyecto web existente. Con la adición de Capgo, incluso es más fácil agregar actualizaciones en vivo a tu aplicación, asegurando que tus usuarios siempre tengan acceso a las últimas características y correcciones de errores.

Aprende cómo Capgo puede ayudarte a construir aplicaciones mejoradas más rápido, regístrate para una cuenta gratuita hoy.

Sigue adelante desde Construyendo Aplicaciones Móviles con Vue y Capacitor

Si estás utilizando Construyendo Aplicaciones Móviles con Vue y Capacitor para planificar el comportamiento de medios y interfaz nativa, conecta con Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades-en-vivo para el detalle de implementación en @capgo/capacitor-actividades-en-vivo, Usando @capgo/capacitor-reproductor-de-videos For la capacidad nativa en Usando @capgo/capacitor-video-player, @capgo/capacitor-video-player Para el detalle de implementación en @capgo/capacitor-video-player, y Usando @capgo/capacitor-native-navigation Para la capacidad nativa en Usando @capgo/capacitor-native-navigation.