Développer des applications mobiles avec Vue et Capacitor

Dans ce tutoriel, nous allons vous guider pour convertir une application web Vue en une application mobile native avec Capacitor. Vous pouvez également ajouter Capgo Native Navigation and Transitions pour un rendu mobile natif, et utiliser tailwind-capacitor pour les safe areas.

À propos de Capacitor

Capacitor est un outil révolutionnaire qui s'intègre facilement à n'importe quel projet web pour convertir votre application en application mobile native. Il génère pour vous des projets Xcode et Android Studio natifs et permet d'accéder aux fonctionnalités natives de l'appareil, comme la caméra, via un bridge JavaScript.

Préparer votre application Vue

Tout d'abord, créez une nouvelle application Vue en exécutant la commande suivante :

vue create my-app
cd my-app
npm install

Pour préparer votre application Vue au déploiement mobile natif, vous devrez exporter votre projet. Ajoutez un script dans votre package.json pour compiler et copier le projet Vue :

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

Après avoir exécuté la commande build , vous devriez voir un nouveau dist dossier dans le répertoire racine de votre projet. Ce dossier sera utilisé plus tard par Capacitor.

Ajouter Capacitor à votre application Vue

Pour convertir votre application web Vue en un conteneur mobile natif, suivez ces étapes :

Installez le CLI Capacitor en tant que dépendance de développement et configurez-le dans votre projet. Acceptez les valeurs par défaut pour le nom et le bundle ID lors de la configuration.
Installez le package core et les packages correspondants pour les plateformes iOS et Android.
Ajoutez les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de votre projet :

# 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

Vous devriez maintenant voir de nouveaux iOS et android dossiers dans votre projet Vue.

Mettre à jour le capacitor.config.json pour pointer le webDir vers le résultat de votre commande de build :

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

Maintenant, vous pouvez compiler votre projet Vue et le synchroniser avec Capacitor :

npm run build
npx cap sync

Compiler et déployer des apps natives

Pour développer des apps iOS, vous devez avoir Xcode installé et, pour les apps Android, Android Studio. Vous devez aussi vous inscrire à l'Apple Developer Program pour iOS et à la Google Play Console pour Android afin de distribuer votre app sur les stores.

Utilisez Capacitor CLI pour ouvrir les deux projets natifs :

npx cap open ios
npx cap open android

Déployez votre app sur un appareil connecté via Android Studio ou Xcode.

Capacitor Live Reload

Activez le live reload sur votre appareil mobile en configurant l'app Capacitor pour charger le contenu depuis une URL spécifique de votre réseau.

Trouvez votre adresse IP locale et mettez à jour le capacitor.config.ts fichier avec l'IP et le port corrects :

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;

Appliquez ces changements en les copiant dans votre projet natif :

npx cap copy

Now, your app will automatically reload and show changes when you update your Vue app.

Utiliser les plugins Capacitor

Installez un plugin Capacitor, comme le plugin Share, et utilisez-le dans votre app Vue :

npm i @capacitor/share

Importez le package et appelez la share() fonction dans votre application :

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

Après avoir installé de nouveaux plugins, lancez la sync et redéployez l'application sur votre appareil :

npx cap sync

Ensuite, vous pouvez rendre l'application plus native sur iOS et Android grâce à la navigation et aux transitions Capgo, et corriger les problèmes de mise en page iOS courants qui causent des débordements horizontaux ou des zones de sécurité coupées.

J'ai travaillé pendant des années avec Ionic pour compiler des applications multiplateformes, mais l'intégrer à Vue est laborieux et rarement rentable si vous utilisez déjà Tailwind CSS.

Pour un rendu mobile natif dans une application Vue + Capacitor, utilisez les plugins Capgo plutôt que des kits UI uniquement web comme Konsta UI :

@capgo/capacitor-native-navigation — navbar native, barre d'onglets Liquid Glass sur iOS et style de barre d'onglets floutée sur Android. Votre routeur Vue conserve 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 :

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Configurez 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 système ; Android utilise un arrière-plan 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 :

bun add -D tailwind-capacitor

Dans src/assets/main.css:

@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 Vue, 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 si modifier uniquement la balise viewport ne suffit pas. Effectuez ces vérifications dans l'ordre.

Assurez-vous que la balise meta viewport est correctement appliquée

Ajoutez la balise meta viewport dans index.html inside <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,
#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.tspréférez la désactivation des insets natifs et laissez le CSS (ou la navigation native) contentInsetMode: 'css') gérer la safe area :

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

Mélanger l'automatic content inset 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. Avec l'ajout de Capgo, il est encore plus facile d'ajouter des live updates à votre app, garantissant que vos utilisateurs accèdent toujours aux dernières fonctionnalités et corrections de bugs.

Learn how Capgo can help you build better apps faster, créez un compte gratuit today.

Pour aller plus loin après la création d'apps mobiles avec Vue et Capacitor

Si vous utilisez Développer des applications mobiles avec Vue et Capacitor pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la fonctionnalité native dans la section Utiliser @capgo/capacitor-video-player, @capgo/capacitor-video-player pour les détails d'implémentation dans @capgo/capacitor-video-player, et Utilisation de @capgo/capacitor-native-navigation pour la capacité native avec l'utilisation de @capgo/capacitor-native-navigation.