Dans ce tutoriel, nous allons commencer par créer une nouvelle application web avec Quasar. Ensuite, nous verrons comment la transformer en application mobile avec Capacitor. Si vous voulez que votre application soit plus belle sur mobile.
Avec Capacitor, vous pouvez transformer votre application web Quasar en application mobile sans avoir à faire des choses compliquées ni à apprendre une toute nouvelle façon de créer des apps, comme avec React Native.
Ce tutoriel vous guidera tout au long du processus, en partant d'une nouvelle application Quasar pour ensuite intégrer Capacitor afin de passer au monde des applications mobiles natives. De plus, vous utiliserez Capgo to send live update to your app in seconds.
À propos de Capacitor
CapacitorJS change vraiment la donne ! Vous pouvez l'intégrer sans effort à n'importe quel projet web, et il encapsulera votre application dans une webview native, générant pour vous les projets Xcode et Android Studio natifs. De plus, ses plugins permettent d'accéder aux fonctionnalités natives de l'appareil, comme la caméra, via un bridge JS.
Avec Capacitor, vous obtenez une excellente application mobile native sans configuration complexe ni courbe d'apprentissage raide. Son API léger et ses fonctionnalités épurées le rendent très facile à intégrer à votre projet. Croyez-moi, vous serez surpris de la facilité avec laquelle on obtient une application native pleinement fonctionnelle avec Capacitor !
Préparer votre application Quasar
Pour créer une nouvelle application Quasar, lancez la commande suivante :
npm init quasar
Choisissez l'option « App with Quasar CLI » puis « Quasar v2 ».
Pour créer une application mobile native, il nous faut un Exporter de notre projet. Ajoutons donc un script simple dans notre package.json que vous pouvez utiliser pour compiler et copier le projet Quasar :
{
"scripts": {
// ...
"build": "quasar build"
}
}Après avoir exécuté la commande generate, vous devriez voir apparaître un nouveau dist dossier à la racine de votre projet.
Ce dossier sera utilisé par Capacitor par la suite, mais pour l'instant, nous devons le configurer correctement.
Ajouter Capacitor à votre application Quasar
Pour packager n'importe quelle application web dans un conteneur mobile natif, il faut suivre quelques étapes initiales, mais ensuite, il suffit d'exécuter une seule sync commande.
Tout d'abord, nous pouvons installer le Capacitor CLI en tant que dépendance de développement, puis nous l'installons dans notre projet. Lors de la configuration, vous pouvez appuyer sur « entrée » pour accepter les valeurs par défaut du nom et du bundle ID.
Ensuite, nous devons installer le package core ainsi que les packages nécessaires pour les plateformes iOS et Android.
Enfin, nous pouvons ajouter les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de notre projet :
# 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
À ce stade, vous devriez pouvoir voir de nouveaux ios et Android dossiers dans votre projet Quasar.
Ce sont de véritables projets natifs !
Pour accéder au projet Android plus tard, vous devez installer Android Studio. Pour iOS, vous avez besoin d'un Mac et devez installer Xcode.
De plus, vous devriez trouver un fichier capacitor.config.ts dans votre projet, qui contient des paramètres Capacitor fondamentaux utilisés lors de la synchronisation. La seule chose à laquelle vous devez prêter attention est le webDir, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est incorrect.
Pour corriger cela, ouvrez le fichier capacitor.config.json et mettez à jour le webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Vous pouvez tester en exécutant les commandes suivantes :
npm run generate
npx cap syncLa première commande npm run generate va simplement compiler votre projet Quasar et copier le build statique, tandis que la deuxième commande npx cap sync synchronisera tous les code web vers les emplacements appropriés des plateformes natives afin qu'ils puissent être affichés dans une application.
De plus, la commande sync peut mettre à jour les plateformes natives et installer des plugins, donc lorsque vous installez un nouveau Plugins Capacitor il est temps de lancer npx cap sync à nouveau.
Sans même vous en rendre compte, c'est terminé ! Voyons maintenant l'application sur un appareil.
Compiler et déployer des apps natives
Pour développer des apps iOS, vous devez avoir Xcode installé, et pour les apps Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez de distribuer votre app sur les stores, vous devez vous inscrire à l'Apple Developer Program pour iOS et à la Google Play Console pour Android.
Si vous débutez dans le développement mobile natif, vous pouvez utiliser le Capacitor CLI pour ouvrir facilement les deux projets natifs :
npx cap open ios
npx cap open androidUne fois vos projets natifs configurés, déployer votre application sur un appareil connecté est simple. Dans Android Studio, il vous suffit d'attendre que tout soit prêt pour déployer votre application sur un appareil connecté sans changer le moindre paramètre. Voici un exemple :
Dans Xcode, vous devez configurer votre compte de signature pour déployer votre application sur un appareil réel plutôt que sur le simulateur. Si vous ne l'avez jamais fait, Xcode vous guide tout au long du processus (mais là encore, vous devez être inscrit au Developer Program). Ensuite, il vous suffit de cliquer sur play pour lancer l'application sur votre appareil connecté, que vous pouvez sélectionner en haut. Voici un exemple :
Félicitations ! Vous avez déployé avec succès votre application web Quasar sur un appareil mobile. Voici un exemple :
Mais attendez, il existe aussi un moyen plus rapide de faire cela pendant le développement…
Capgo Live Update
Capgo Live Update est un service qui permet aux développeurs de déployer des mises à jour sur leurs applications mobiles sans passer par le processus traditionnel de publication sur les stores. C'est un moyen pratique de corriger rapidement des bugs ou d'apporter de petites mises à jour à une application sans attendre le processus de validation de l'App Store.
L'intégration de Capgo dans votre application Quasar est un processus simple qui vous permet de profiter de la puissance des live updates en temps réel. Ce guide étape par étape vous accompagnera dans l'intégration et l'implémentation de Capgo Live Update, vous permettant de livrer des mises à jour fluides.
Inscrivez-vous et accédez au dashboard Capgo:
Il est temps de vous inscrire et de récupérer votre clé API pour envoyer votre première version ! Commencez par créer un compte Capgo.
Installez le Capgo SDK:
Depuis votre terminal, directement à la racine de votre application Capacitor, lancez :
npm i @capgo/capacitor-updater && npx cap sync Pour installer le plugin dans votre application Capacitor.
Ajoutez ensuite code à votre application pour remplacer CodePush :
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Cela indiquera au plugin natif que l'installation a réussi.
Connectez-vous à Capgo Cloud:
Tout d'abord, utilisez la all clé API présente dans votre compte pour vous connecter avec le CLI :
`npx @capgo/cli@latest login YOU_KEY`Ajouter votre première application:
Commençons par créer une application dans le cloud Capgo avec CLI.
npx @capgo/cli@latest app addCette commande utilisera toutes les variables définies dans le fichier de config Capacitor pour créer l'app.
Envoyer votre première version:
Lancez la commande pour compiler votre code et l'envoyer sur Capgo avec :
npx @capgo/cli@latest bundle upload`Par défaut, le nom de la version sera celui de votre fichier package.json.
Vérifiez dans Capgo si le build est présent.
Vous pouvez même le tester avec mon app mobile sandbox.
Définir le canal par défaut:
Une fois votre application envoyée vers Capgo, vous devez définir votre canal par défaut pour que les apps puissent recevoir les Live Updates de Capgo.
npx @capgo/cli@latest channel set production -s default
Configurer l'app pour valider les mises à jour:
Ajoutez cette config à votre fichier JavaScript principal.
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Then do a npm run build && npx cap copy pour mettre à jour votre application.
Recevez un Live Update:
Pour que votre application reçoive un live update depuis Deploy, vous devrez lancer l'app sur un appareil ou un émulateur. Le plus simple est d'utiliser la commande suivante pour lancer votre app en local sur un émulateur ou un appareil connecté à votre ordinateur.
npx cap run [ios | android]Ouvrez l'app, passez-l’en arrière-plan puis rouvrez-la ; vous devriez voir dans les logs que l'app a effectué la mise à jour.
Félicitations ! 🎉 Vous avez déployé avec succès votre premier Live Update. Ce n'est que le début de ce que vous pouvez accomplir avec les Live Updates. Pour en savoir plus, consultez la documentation complète sur les Live Updates.
Utiliser les plugins Capacitor
Voyons comment utiliser un plugin Capacitor en pratique, que nous avons déjà évoqué plusieurs fois. Pour cela, nous pouvons installer un plugin assez simple en exécutant :
npm i @capacitor/shareIl n'y a rien de sorcier dans le plugin Share, mais il affiche quand même la boîte de dialogue de partage native ! Pour cela, il suffit désormais d'importer le package et d'appeler la share() fonction de notre application, alors changeons le pages/index.vue comme ceci :
<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>Comme mentionné plus haut, quand on installe de nouveaux plugins, il faut faire une sync puis redéployer l'application sur notre appareil. Pour cela, lancez la commande suivante :
npx cap syncUne fois le bouton cliqué, vous pourrez voir le superbe dialogue de partage natif en action !
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec la navigation et les transitions Capgo, et corriger les problèmes de mise en page iOS courants qui causent des débordements horizontaux ou des safe areas rognées.
Une interface fluide avec Capgo Native Navigation et Transitions
J'ai travaillé pendant des années avec Ionic pour compiler des applications multiplateformes, mais l'intégrer à Quasar est laborieux et rarement rentable si vous utilisez déjà Tailwind CSS.
Pour un rendu mobile natif dans une application Quasar + Capacitor, utilisez les plugins Capgo plutôt que des kits UI web comme Konsta UI :
- @capgo/capacitor-native-navigation — une navbar native, une barre d'onglets Liquid Glass sur iOS et un style de barre d'onglets floutée sur Android. Votre routeur Quasar gère l'état des routes ; le plugin gère l'interface native.
- @capgo/capacitor-transitions — des transitions de page façon Ionic et le swipe-back depuis le bord sur iOS dans la couche WebView, sans adopter l'UI Ionic.
Installez les deux :
npm add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npmx cap syncConfigurez la navigation native avec le mode CSS inset pour que le contenu web respecte les barres natives :
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Affichez une barre d'onglets Liquid Glass (iOS utilise le rendu du système ; Android utilise un fond WebView flouté) :
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}`);
});Ajoutez des transitions de page natives dans votre 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>Enveloppez les pages routées dans cap-router-outlet, cap-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant de naviguer. Ne dupliquez pas les headers ou footers web lorsque la navigation native gère ces surfaces.
Consultez les guides complets : Utilisation de @capgo/capacitor-native-navigation et Utiliser @capgo/capacitor-transitions.
Safe areas avec Tailwind
Pour les safe areas de l'appareil avec Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas utilitaires et d'autres plugins Tailwind compatibles Capacitor :
npm add -D tailwind-capacitorDans src/css/app.scss:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des utilitaires tels que pt-safe, pb-safe, et px-safe au lieu de parsemer env(safe-area-inset-*) à la main. Le projet est activement développé — s'il manque quelque chose pour votre configuration Quasar, ouvrez une PR sur GitHub.
Corriger les problèmes de mise en page iOS (viewport, zone sécurisée et débordement horizontal)
Si le contenu semble coupé, décalé ou défile horizontalement sur iOS, ajouter plus de overflow-x: hidden ou le simple ajustement de la balise viewport ne règle généralement pas le problème. Effectuez ces vérifications dans l'ordre.
Assurez-vous que la balise meta viewport est correctement appliquée
Dans index.html (ou votre template HTML Quasar), configurez la balise meta viewport dans <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérez la safe area iOS depuis un seul wrapper racine
Créez un shell d'application unique et appliquez-y le padding de la safe area — pas dans plusieurs composants imbriqués :
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);
}Enveloppez tout le contenu de la page dans .app-shell. Un padding de safe area dupliqué dans les headers, les modales et les wrappers de layout donne souvent l'impression que l'UI est rognée ou trop grande.
Avec @capgo/tailwind-capacitor, vous pouvez obtenir le même padding avec des utilitaires comme pt-safe pb-safe px-safe sur ce shell unique.
Configurez Capacitor iOS contentInset vers never d'abord
Dans capacitor.config.ts, préférez désactiver les insets natifs et laissez le CSS (ou la contentInsetMode: 'css') gèrent la safe area :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist/spa',
ios: {
contentInset: 'never',
},
};Combiner le content inset automatique de Capacitor avec le CSS env(safe-area-inset-*) le padding est une cause fréquente de double espacement.
Trouvez l'élément qui déborde réellement
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou un grand min-width.
Dans le Web Inspector de Safari, lancez :
[...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,
}));Avec Tailwind, remplacez w-screen par w-full dès que possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, d'un padding safe-area dupliqué, ou d'un conteneur à largeur fixe — et non de la balise meta viewport elle-même.
Conclusion
Capacitor est une excellente option pour créer des applications natives à partir d'un projet web existant, offrant un moyen simple de partager code et de maintenir une interface cohérente.
Et avec l'ajout de Capgo, il est encore plus facile d'ajouter des live updates à votre application, garantissant que vos utilisateurs bénéficient toujours des dernières fonctionnalités et corrections de bugs.
Si vous souhaitez apprendre à ajouter Capgo à votre application Next.js, consultez l'article suivant :
Poursuivez avec Créer des applications mobiles avec les live updates, Quasar et Capacitor.
Si vous utilisez Créer des applications mobiles avec les live updates, Quasar et Capacitor. pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.
