En este tutorial, empezaremos creando una nueva web app usando Quasar. Más adelante, aprenderemos a convertirla en una app móvil usando Capacitor. Si quieres que tu app luzca mejor en móviles.
Con Capacitor, puedes convertir tu web app de Quasar en una app móvil sin tener que hacer procesos complejos ni aprender una forma totalmente nueva de crear apps, como pasaría con React Native.
Este tutorial te guiará paso a paso, empezando con una nueva app de Quasar para luego integrar Capacitor y entrar en el mundo de las apps móviles nativas. Además, usarás Capgo para enviar live update a tu app en cuestión de segundos.
Acerca de Capacitor
¡CapacitorJS es un auténtico antes y después! Puedes integrarlo sin esfuerzo en cualquier proyecto web y envolverá tu aplicación en una webview nativa, generando los proyectos de Xcode y Android Studio por ti. Además, sus plugins permiten acceder a funciones nativas del dispositivo, como la cámara, mediante un bridge de JS.
Con Capacitor, obtienes una app móvil nativa fantástica sin configuraciones complicadas ni una curva de aprendizaje pronunciada. Su ligero API y su funcionalidad optimizada hacen que integrarlo en tu proyecto sea pan comido. ¡Créeme, te sorprenderá lo fácil que es conseguir una app nativa totalmente funcional con Capacitor!
Preparando tu app de Quasar
Para crear una nueva app de Quasar, ejecuta el siguiente comando:
npm init quasar
Elige la opción “App with Quasar CLI” y luego “Quasar v2”.
Para crear una app móvil nativa, necesitamos un Exportar de nuestro proyecto. Así que añadamos un script sencillo en nuestro package.json que puedes usar para build y copiar el proyecto Quasar:
{
"scripts": {
// ...
"build": "quasar build"
}
}Tras ejecutar el comando generate, deberías poder ver un nuevo dist carpeta en la raíz de tu proyecto.
Esta carpeta la usará Capacitor más adelante, pero por ahora debemos configurarla correctamente.
Cómo añadir Capacitor a tu app de Quasar
Para empaquetar cualquier web app en un contenedor móvil nativo, hay que seguir unos pasos iniciales, pero después basta con ejecutar un solo sync comando.
Primero, podemos instalar el Capacitor CLI como dependencia de desarrollo y luego configurarlo en nuestro proyecto. Durante la configuración, puedes pulsar “enter” para aceptar los valores por defecto de name y bundle ID.
A continuación, necesitamos instalar el core package y los paquetes necesarios para las plataformas iOS y Android.
Por fin, podemos añadir las plataformas y Capacitor creará carpetas para cada una en la raíz del proyecto:
# Install the Capacitor CLI locally
npm install -D @capacitor/cli
# Initialize Capacitor in your Quasar 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
A estas alturas, ya deberías poder ver nuevas ios y Android carpetas en tu proyecto Quasar.
¡Son proyectos nativos reales!
Para acceder al proyecto de Android más tarde, debes instalar Android Studio. Para iOS, necesitas un Mac y debes instalar Xcode.
Además, deberías encontrar un capacitor.config.ts archivo en tu proyecto, que contiene algunos ajustes fundamentales de Capacitor que se usan durante la sincronización. Lo único a lo que debes prestar atención es al webDir, que debe apuntar al resultado de tu comando de build. Actualmente, es incorrecto.
Para corregirlo, abre el archivo capacitor.config.json y actualiza el webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Puedes probarlo ejecutando los siguientes comandos:
npm run generate
npx cap syncEl primer comando npm run generate simplemente compilará tu proyecto Quasar y copiará el build estático, mientras que el segundo comando npx cap sync sincronizará todos los code web en los lugares correctos de las plataformas nativas para que se muestren en una app.
Además, el comando sync podría actualizar las plataformas nativas e instalar plugins, así que cuando instales un nuevo plugins de Capacitor es hora de ejecutar npx cap sync de nuevo.
¡Sin darte cuenta, ya has terminado, así que veamos la app en un dispositivo!
Build y deploy de apps nativas
Para desarrollar apps de iOS, necesitas tener Xcode instalado, y para apps de Android, necesitas tener Android Studio instalado. Además, si planeas distribuir tu app en la tienda de apps, debes inscribirte en el Apple Developer Program para iOS y en la Google Play Console para Android.
Si eres nuevo en el desarrollo móvil nativo, puedes usar el Capacitor CLI para abrir ambos proyectos nativos fácilmente:
npx cap open ios
npx cap open androidUna vez configurados tus proyectos nativos, desplegar tu app en un dispositivo conectado es fácil. En Android Studio, solo debes esperar a que todo esté listo y podrás desplegar tu app sin cambiar ningún ajuste. Aquí tienes un ejemplo:
En Xcode, debes configurar tu cuenta de firma para desplegar la app en un dispositivo real en lugar de solo en el simulador. Si no lo has hecho antes, Xcode te guía en el proceso (pero recuerda que debes estar inscrito en el Developer Program). Después, solo tienes que darle al play para ejecutar la app en tu dispositivo conectado, que puedes seleccionar arriba. Aquí tienes un ejemplo:
¡Felicidades! Has desplegado con éxito tu web app de Quasar en un dispositivo móvil. Aquí tienes un ejemplo:
Pero espera, también hay una forma más rápida de hacer esto durante el desarrollo…
Capgo Live Update
Capgo Live Update es un servicio que permite a los desarrolladores desplegar actualizaciones en sus apps móviles sin pasar por el proceso de envío tradicional de la App Store. Es una forma cómoda de corregir bugs rápido o hacer pequeñas actualizaciones en una app sin esperar la revisión de la App Store.
Integrar Capgo en tu app de Quasar es un proceso sencillo que te permite aprovechar el poder de las actualizaciones en tiempo real. Esta guía paso a paso te enseñará cómo integrar e implementar Capgo Live Update para ofrecer actualizaciones sin interrupciones.
Regístrate y accede al dashboard de Capgo:
¡Es hora de registrarte y obtener tu clave de API para subir tu primera versión! Empieza por crear una cuenta de Capgo.
Instala el SDK de Capgo:
Desde la terminal, directamente en la raíz de tu app Capacitor, ejecuta:
npm i @capgo/capacitor-updater && npx cap sync Para instalar el plugin en tu app de Capacitor.
Y luego añade code a tu app como reemplazo de CodePush:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Esto le indicará al plugin nativo que la instalación fue exitosa.
Inicia sesión en Capgo CLOUD:
Primero, usa el all apikey presente en tu cuenta para iniciar sesión con CLI:
`npx @capgo/cli@latest login YOU_KEY`Añade tu primera App:
Empecemos creando una app en Capgo Cloud con el CLI.
npx @capgo/cli@latest app addEste comando usará todas las variables definidas en el archivo de config de Capacitor para crear la app.
Sube tu primera versión:
Ejecuta el comando para hacer el build de tu code y enviarlo a Capgo con:
npx @capgo/cli@latest bundle upload`Por defecto, el nombre de la versión será el de tu archivo package.json.
Comprueba en Capgo si el build está presente.
Incluso puedes probarlo con mi app móvil de sandbox.
Establecer canal como predeterminado:
Tras enviar tu app a Capgo, debes configurar tu canal como predeterminado para que las apps reciban actualizaciones de Capgo.
npx @capgo/cli@latest channel set production -s default
Configura la app para validar actualizaciones:
Añade esta configuración a tu archivo JavaScript principal.
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Luego ejecuta un npm run build && npx cap copy para actualizar tu app.
Recibe un Live Update:
Para que tu aplicación reciba un live update desde Deploy, deberás ejecutar la app en un dispositivo o emulador. La forma más fácil es usar el siguiente comando para lanzar tu app local en un emulador o en un dispositivo conectado a tu ordenador.
npx cap run [ios | android]Abre la app, ponla en segundo plano y ábrela de nuevo; deberías ver en los logs que la app hizo la actualización.
¡Felicidades! 🎉 Has desplegado con éxito tu primer Live Update. Esto es solo el comienzo de lo que puedes hacer con Live Updates. Para saber más, consulta la documentación de Live Updates.
Uso de Capacitor Plugins
Veamos cómo funciona un plugin de Capacitor, algo que ya hemos mencionado antes. Para empezar, podemos instalar un plugin muy sencillo ejecutando:
npm i @capacitor/shareNo hay nada especial en el plugin Share, pero aun así abre el diálogo nativo de compartir. Para esto ahora solo necesitamos importar el paquete y llamar al correspondiente share() función desde nuestra app, así que cambiemos pages/index.vue a esto:
<template>
<div>
<h1>Welcome to Quasar 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>Como mencionamos antes, al instalar nuevos plugins, debemos hacer un sync y luego volver a desplegar la app en nuestro dispositivo. Para ello, ejecuta el siguiente comando:
npx cap sync¡Tras pulsar el botón, podrás ver el magnífico diálogo nativo de compartir en acción!
Después, puedes hacer que la app se sienta más nativa en iOS y Android con la navegación y las transiciones de Capgo, y solucionar problemas comunes de layout en iOS que causan desbordamiento horizontal o áreas seguras recortadas.
UI con sensación nativa, navegación y transiciones nativas de Capgo
He trabajado durante años con Ionic para crear aplicaciones multiplataforma, pero integrarlo con Quasar es un parche y rara vez vale la pena si ya tienes Tailwind CSS.
Para una sensación nativa en una app de Quasar + Capacitor, usa plugins de Capgo en lugar de UI kits web como Konsta UI:
- @capgo/capacitor-native-navigation — navbar nativa, Liquid Glass tab bar en iOS y un estilo de tab bar con desenfoque en Android. El router de Quasar gestiona el estado de las rutas; el plugin controla el chrome nativo.
- @capgo/capacitor-transitions — transiciones de página estilo Ionic y swipe-back desde el borde en iOS en la capa WebView, sin adoptar Ionic UI.
Instala ambos:
npm add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npmx cap syncConfigura la navegación nativa con CSS inset mode 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',
},
});Renderiza una tab bar Liquid Glass (iOS usa renderizado del sistema; Android usa un fondo WebView con desenfoque):
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}`);
});Añade transiciones de página nativas en tu app shell:
<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 las páginas enrutadas en cap-router-outlet, cap-page, y cap-content, y llama a setDirection('forward') o setDirection('back') antes de navegar. No dupliques headers o footers web si la navegación nativa ya gestiona esas áreas.
Consulta las guías completas: Uso de @capgo/capacitor-native-navigation y Uso de @capgo/capacitor-transitions.
Safe areas con Tailwind
Para las safe areas del dispositivo en Tailwind CSS, usa @capgo/tailwind-capacitor (publicado como tailwind-capacitor en npm). Proporciona safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor:
npm add -D tailwind-capacitorEn src/css/app.scss:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Usa utilidades como pt-safe, pb-safe, y px-safe en lugar de añadir env(safe-area-inset-*) manualmente. El proyecto está en desarrollo activo — si falta algo para tu configuración de Quasar, abre un PR en GitHub.
Cómo solucionar problemas de layout en iOS (viewport, safe area y overflow horizontal)
Si el contenido se ve recortado, desplazado o con scroll horizontal en iOS, añadir más overflow-x: hidden o ajustar solo la etiqueta viewport no suele solucionarlo. Revisa estas comprobaciones en orden.
Asegúrate de que la meta tag viewport esté bien aplicada
En index.html (o tu plantilla HTML de Quasar), configura la etiqueta meta viewport en <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gestiona el safe area de iOS desde un único wrapper raíz
Crea un único app shell y aplica el padding de safe area ahí, no en múltiples componentes anidados:
html,
body,
#q-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 de .app-shell. El padding de safe-area duplicado en headers, modales y wrappers de layout suele hacer que la UI parezca recortada o demasiado grande.
Con @capgo/tailwind-capacitor, puedes aplicar el mismo padding usando utilidades como pt-safe pb-safe px-safe en ese único shell.
Configura Capacitor iOS contentInset a never primero
En capacitor.config.ts, prefiere desactivar el inset nativo y dejar que CSS (o la navegación nativa) contentInsetMode: 'css') se encargue del safe area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist/spa',
ios: {
contentInset: 'never',
},
};Combinar el content inset automático de Capacitor con CSS env(safe-area-inset-*) es una causa común de espaciado doble.
Encuentra el elemento que realmente desborda
El culpable habitual es un elemento que usa 100vw, Tailwind w-screen, un ancho fijo en píxeles, 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 siempre que sea posible. Muchos problemas de desbordamiento horizontal vienen de 100vw / w-screen, padding de safe-area duplicado o un contenedor de ancho fijo, no del propio meta tag del viewport.
Conclusión
Capacitor es una opción excelente para crear aplicaciones nativas a partir de un proyecto web existente, ya que ofrece una forma sencilla de compartir code y mantener una UI consistente.
Y con la incorporación de Capgo, es aún más fácil añadir live updates a tu app, asegurando que tus usuarios siempre tengan acceso a las últimas funciones y correcciones de errores.
Si quieres aprender a añadir Capgo a tu app de Next.js, echa un vistazo al siguiente artículo:
Continúa con Creating Mobile Apps with live updates, Quasar and Capacitor.
Si estás usando Creación de apps móviles con live updates, Quasar y Capacitor. para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo en Alternativas a plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds.
