In questo tutorial, inizieremo creando una nuova web app con Quasar. Successivamente, vedremo come trasformarla in un'app mobile usando Capacitor. Se vuoi rendere la tua app più bella su mobile.
Con Capacitor, puoi trasformare la tua web app Quasar in un'app mobile senza dover fare tante cose difficili o imparare un modo completamente nuovo di creare app come faresti con React Native.
Questo tutorial ti guiderà passo dopo passo: partiremo da una nuova app Quasar per poi integrare Capacitor e fare il salto nel mondo delle app mobile native. Inoltre, userai Capgo per inviare live update alla tua app in pochi secondi.
Informazioni su Capacitor
CapacitorJS è una vera rivoluzione! Puoi integrarlo senza sforzo in qualsiasi progetto web: avvolgerà la tua applicazione in una webview nativa, generando automaticamente i progetti Xcode e Android Studio. Inoltre, i suoi plugin permettono di accedere alle funzioni native del dispositivo, come la fotocamera, tramite un bridge JS.
Con Capacitor, ottieni una fantastica app mobile nativa senza configurazioni complicate né curve di apprendimento ripide. Il suo API leggero e le funzionalità snelle lo rendono semplicissimo da integrare nel tuo progetto. Fidati, rimarrai stupito da quanto sia facile ottenere un'app nativa pienamente funzionante con Capacitor!
Preparazione della tua app Quasar
Per creare una nuova app Quasar, esegui questo comando:
npm init quasar
Seleziona l'opzione “App con Quasar CLI” e poi “Quasar v2”.
Per creare un'app mobile nativa, ci serve un export del nostro progetto. Quindi aggiungiamo uno script semplice nel nostro package.json che puoi usare per build e copiare il progetto Quasar:
{
"scripts": {
// ...
"build": "quasar build"
}
}Dopo aver eseguito il comando generate, dovresti essere in grado di individuare un nuovo dist cartella nella root del progetto.
Questa cartella verrà utilizzata da Capacitor in seguito, ma per ora dobbiamo configurarla correttamente.
Aggiungere Capacitor alla tua app Quasar
Per impacchettare qualsiasi web app in un container mobile nativo, dobbiamo seguire alcuni passaggi iniziali, ma dopo basta eseguire un singolo sync comando.
Per prima cosa, possiamo installare Capacitor CLI come dev dependency e poi configurarlo nel progetto. Durante il setup, puoi premere “enter” per accettare i valori predefiniti di name e bundle ID.
Successivamente, dobbiamo installare il pacchetto core e i pacchetti necessari per le piattaforme iOS e Android.
Infine, possiamo aggiungere le piattaforme e Capacitor creerà le cartelle per ogni piattaforma nella root del progetto:
# 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 questo punto, dovresti essere in grado di osservare nuovi iOS e Android le cartelle nel tuo progetto Quasar.
Sono veri progetti nativi!
Per accedere al progetto Android in seguito, devi installare Android Studio. Per iOS, ti serve un Mac e devi installare Xcode.
Inoltre, dovresti trovare un file capacitor.config.ts nel tuo progetto, che contiene alcune impostazioni fondamentali di Capacitor utilizzate durante la sync. L'unica cosa a cui prestare attenzione è webDir, che deve puntare al risultato del tuo comando di build. Attualmente, non è corretto.
Per risolvere, apri il file capacitor.config.json file e aggiornare il webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Puoi provarlo eseguendo i seguenti comandi:
npm run generate
npx cap syncIl primo comando npm run generate eseguirà semplicemente la build del tuo progetto Quasar e copierà la build statica, mentre il secondo comando npx cap sync sincronizzerà tutti i code web nelle posizioni corrette delle piattaforme native, così da poterli visualizzare nell'app.
Inoltre, il comando sync potrebbe aggiornare le piattaforme native e installare i plugin, quindi quando installi un nuovo plugin Capacitor è il momento di eseguire npx cap sync ancora.
Senza accorgertene, hai finito: ora proviamo l'app su un dispositivo!
Build e deploy di app native
Per sviluppare app iOS, devi avere Xcode installato, mentre per le app Android devi avere Android Studio installato. Inoltre, se intendi distribuire la tua app sugli store, devi iscriverti all'Apple Developer Program per iOS e alla Google Play Console per Android.
Se sei alle prime armi con lo sviluppo mobile nativo, puoi usare Capacitor CLI per aprire facilmente entrambi i progetti nativi:
npx cap open ios
npx cap open androidUna volta configurati i tuoi progetti nativi, distribuire l'app su un dispositivo connesso è semplicissimo. In Android Studio, devi solo attendere che tutto sia pronto e puoi distribuire l'app su un dispositivo connesso senza modificare alcuna impostazione. Ecco un esempio:
In Xcode, devi configurare il tuo account di signing per distribuire l'app su un dispositivo reale invece che solo sul simulatore. Se non l'hai mai fatto, Xcode ti guiderà nel processo (ma ricorda che devi essere iscritto al Developer Program). Dopodiché, ti basterà premere play per avviare l'app sul dispositivo connesso, che puoi selezionare in alto. Ecco un esempio:
Congratulazioni! Hai distribuito con successo la tua web app Quasar su un dispositivo mobile. Ecco un esempio:
Ma aspetta, c'è anche un modo più veloce per farlo durante lo sviluppo...
Capgo Live Update
Capgo Live Update è un servizio che permette agli sviluppatori di distribuire aggiornamenti alle proprie app mobile senza passare dal tradizionale processo di pubblicazione sull'App Store. Può essere un modo pratico per correggere bug rapidamente o fare piccole modifiche a un'app senza attendere la revisione dell'App Store.
Integrare Capgo nella tua app Quasar è un processo semplice che ti permette di sfruttare la potenza dei live update in tempo reale. Questa guida passo dopo passo ti accompagnerà nell'integrazione e nell'implementazione di Capgo Live Update, consentendoti di rilasciare update senza interruzioni.
Registrati e accedi alla dashboard di Capgo:
È il momento di registrarti e ottenere la tua chiave API per fare l'upload della tua prima versione! Inizia creando un account Capgo.
Installa Capgo SDK:
Dalla riga di comando, direttamente nella root della tua app Capacitor, esegui:
npm i @capgo/capacitor-updater && npx cap sync Per installare il plugin nella tua app Capacitor.
E poi aggiungi alla tua app code come alternativa a CodePush:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Questo comunicherà al plugin nativo che l'installazione è riuscita.
Accedi a Capgo CLOUD:
Per prima cosa, usa l' all apikey presente nel tuo account per accedere con CLI:
`npx @capgo/cli@latest login YOU_KEY`Aggiungi la tua prima App:
Iniziamo creando un'app su Capgo Cloud tramite CLI.
npx @capgo/cli@latest app addQuesto comando userà tutte le variabili definite nel file di config di Capacitor per creare l'app.
Carica la tua prima versione:
Esegui il comando per buildare la tua code e inviala a Capgo con:
npx @capgo/cli@latest bundle upload`Di default, il nome della versione sarà quello indicato nel file package.json.
Controlla Capgo se la build è presente.
Puoi anche testarla con la mia app sandbox mobile.
Imposta il canale come default:
Dopo aver inviato la tua app a Capgo, devi impostare il canale come predefinito per permettere alle app di ricevere gli update da Capgo.
npx @capgo/cli@latest channel set production -s default
Configura l'app per validare gli update:
Aggiungi questa configurazione al tuo file JavaScript principale.
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Poi esegui un npm run build && npx cap copy per aggiornare la tua app.
Ricevi un Live Update:
Per ricevere un live update da Deploy, devi avviare l'app su un dispositivo o un emulatore. Il modo più semplice è usare questo comando per lanciare la tua app locale su un emulatore o su un dispositivo collegato al computer.
npx cap run [ios | android]Apri l'app, mettila in background e riaprila: nei log dovresti vedere che l'app ha eseguito l'update.
Complimenti! 🎉 Hai deployato con successo il tuo primo Live Update. Questo è solo l'inizio di quello che puoi fare con Live Updates. Per saperne di più, consulta la documentazione di Live Updates.
Utilizzo dei plugin Capacitor
Vediamo come usare in pratica un plugin Capacitor, di cui abbiamo già parlato un paio di volte. Per farlo, possiamo installare un plugin abbastanza semplice eseguendo:
npm i @capacitor/shareNon c'è niente di speciale in Plugin di condivisione, ma apre comunque il dialog di condivisione nativo! Per farlo, ora basta importare il pacchetto e chiamare la relativa share() funzione dalla nostra app, quindi modifichiamo pages/index.vue in questo modo:
<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>Come accennato prima, quando installi nuovi plugin devi eseguire un'operazione di sync e poi ridistribuire l'app sul dispositivo. Per farlo, esegui questo comando:
npx cap syncDopo aver cliccato il pulsante, potrai vedere il bellissimo dialog di condivisione nativo in azione!
Successivamente, puoi rendere l'app più nativa su iOS e Android con navigazione e transizioni Capgo, e risolvere i comuni problemi di layout su iOS che causano overflow orizzontale o safe area tagliate.
UI dall'aspetto nativo con Capgo Native Navigation and Transitions
Ho lavorato per anni con Ionic per creare app cross-platform, ma integrarlo con Quasar è complicato e raramente ne vale la pena se hai già Tailwind CSS.
Per un feeling mobile nativo in un'app Quasar + Capacitor, usa i plugin Capgo invece di UI kit web-only come Konsta UI:
- @capgo/capacitor-native-navigation — navbar nativa, tab bar Liquid Glass su iOS e stile tab bar sfocato su Android. Il router di Quasar gestisce lo stato delle rotte; il plugin gestisce la UI nativa.
- @capgo/capacitor-transitions — transizioni di pagina in stile Ionic e swipe-back dal bordo su iOS nel layer WebView, senza adottare Ionic UI.
Installa entrambi:
npm add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npmx cap syncConfigura la navigazione nativa con la modalità CSS inset, così il contenuto web rispetta le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Renderizza una tab bar Liquid Glass (iOS usa il rendering di sistema; Android usa un backdrop WebView sfocato):
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}`);
});Aggiungi transizioni di pagina native nell'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>Avvolgi le pagine del router in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima di navigare. Non duplicare header o footer web se la navigazione nativa gestisce già quelle aree.
Guarda le guide complete: Usando @capgo/capacitor-native-navigation e Uso di @capgo/capacitor-transitions.
Safe areas con Tailwind
Per le safe area del dispositivo in Tailwind CSS, usa @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Offre safe-areas utility e altri plugin Tailwind compatibili con Capacitor:
npm add -D tailwind-capacitorIn src/css/app.scss:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Usa utility come pt-safe, pb-safe, e px-safe invece di inserire manualmente env(safe-area-inset-*) a mano. Il progetto è in costante sviluppo — se manca qualcosa per il tuo setup Quasar, apri una PR su GitHub.
Risolvere problemi di layout su iOS (Viewport, Safe Area e overflow orizzontale)
Se i contenuti appaiono tagliati, spostati o con scroll orizzontale su iOS, aggiungere più overflow-x: hidden o modificare il tag viewport di solito non basta. Segui questi controlli in ordine.
Assicurati che il meta tag viewport sia applicato correttamente
In index.html (o nel tuo template HTML Quasar), imposta il meta tag viewport in <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gestisci la safe area di iOS da un unico wrapper root
Crea un unico app shell e applica lì il padding per la safe area — non in più componenti annidati:
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);
}Racchiudi tutto il contenuto della pagina in .app-shell. Il padding della safe-area duplicato in header, modal e wrapper del layout spesso fa apparire l'interfaccia tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi applicare lo stesso padding con utility come pt-safe pb-safe px-safe su quella singola shell.
Imposta Capacitor iOS contentInset a never per primo
In capacitor.config.ts, preferisci disabilitare i native inset e lascia che il CSS (o quella contentInsetMode: 'css'di Native Navigation) gestisca la safe area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist/spa',
ios: {
contentInset: 'never',
},
};Mescolare l'automatic content inset di Capacitor con il CSS env(safe-area-inset-*) il padding è una causa comune di spaziature doppie.
Trova il vero elemento che causa l'overflow
Il colpevole di solito è un elemento che usa 100vw, Tailwind w-screen, una larghezza fissa in pixel o un grande min-width.
In Safari Web Inspector, esegui:
[...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, sostituisci w-screen con w-full quando possibile. Molti problemi di overflow orizzontale derivano da 100vw / w-screen, padding della safe-area duplicato o un contenitore a larghezza fissa — non dal meta tag viewport stesso."
Conclusione
Capacitor è un'ottima opzione per creare applicazioni native partendo da un progetto web esistente, offrendo un modo semplice per condividere code e mantenere una UI coerente.
E con l'aggiunta di Capgo, è ancora più facile aggiungere live updates alla tua app, così i tuoi utenti hanno sempre accesso alle ultime funzionalità e ai bug fix.
Se vuoi scoprire come aggiungere Capgo alla tua app Next.js, leggi il prossimo articolo:
Continua la lettura da Creare Mobile App con live updates, Quasar e Capacitor.
Se stai usando Creare app mobile con live updates, Quasar e Capacitor. per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli sull'implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow di prodotto in Capgo Native Builds.
