Convertissez votre app Nuxt en iOS et Android avec Capacitor 8

Introduction

Vous avez déjà une application web Nuxt ? Dans ce guide, vous apprendrez à la transformer en applications mobiles natives iOS et Android en utilisant Capacitor 8 — la dernière version avec des performances améliorées et de nouvelles fonctionnalités.

Capacitor enveloppe votre application web dans un conteneur natif, vous donnant accès aux API de l'appareil comme la caméra, le système de fichiers et les notifications push, tout en conservant votre base de code Vue actuelle. Contrairement à Flutter ou React Native, vous n'avez rien à réécrire — votre code Nuxt s'exécute tel quel.

Ce que vous allez apprendre :

Configurer votre application Nuxt actuelle pour la génération statique
Ajouter Capacitor 8 avec les plugins natifs essentiels
Compiler et tester sur des simulateurs iOS et Android
Activer le live reload pour un développement plus rapide
Corriger les problèmes de mise en page iOS courants (viewport, safe area, overflow horizontal)
Ajouter une interface native avec Capgo Native Navigation et Transitions

Vous souhaitez lancer un nouveau projet de zéro ? Consultez notre guide sur Créer une application mobile Nuxt de zéro.

Les avantages de Nuxt et Capacitor

Réutilisabilité Code: Partagez vos composants et votre logique Vue entre vos apps web et mobiles.
Performance: La génération statique de Nuxt crée des bundles optimisés, parfaits pour le mobile.
Capacités natives: Accédez aux fonctionnalités de l'appareil comme la caméra, la géolocalisation et le système de fichiers via les plugins Capacitor.
Développement simplifié: Utilisez vos patterns Vue/Nuxt habituels sans apprendre le développement natif.

Prerequisites

Avant de commencer, assurez-vous d'avoir :

Node.js 18+ installé
Un Nuxt 4 application
Xcode (pour le développement iOS, macOS uniquement)
Android Studio (pour le développement Android)

Configurer votre application Nuxt pour le mobile

La première étape consiste à configurer votre application Nuxt pour la génération statique. Capacitor a besoin de fichiers HTML/JS/CSS statiques pour les inclure dans le bundle de l'application native.

Assurez-vous que votre package.json possède le script generate :

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Important : Si vous utilisez des fonctionnalités côté serveur (API routes, middleware serveur, etc.), vous devrez les refactoriser pour utiliser des alternatives côté client ou des API externes.

Testez la génération statique en exécutant :

bun run generate

Vous devriez voir un .output/public dossier contenant vos fichiers statiques. C'est ce que Capacitor inclura dans le bundle de votre application native.

Ajouter Capacitor 8 à votre projet

Pour packager votre application Nuxt dans un conteneur mobile natif, suivez ces étapes :

Installez le core Capacitor et CLI :

bun add @capacitor/core
bun add -D @capacitor/cli

Installez les plugins Capacitor courants dont vous aurez probablement besoin :

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

Ces plugins offrent des fonctionnalités essentielles :

@capacitor/app: Gérer les événements du cycle de vie de l'app (premier plan/arrière-plan, deep links)
@capacitor/keyboard: Contrôler le comportement du clavier sur mobile
@capacitor/splash-screen: Gérer le splash screen natif
@capacitor/status-bar: Styliser la barre d'état de l'appareil
@capacitor/preferences: Stockage clé-valeur (comme localStorage mais natif)

Initialisez Capacitor avec les détails de votre projet :

bunx cap init my-app com.example.myapp --web-dir .output/public

Remplacer my-app avec le nom de votre app et com.example.myapp avec l'ID de votre application (notation de domaine inversée).

Créez ou mettez à jour le capacitor.config.ts fichier avec la configuration appropriée :

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

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

Installez les plateformes natives :

bun add @capacitor/ios @capacitor/android

Ajoutez les dossiers des plateformes natives :

bunx cap add ios
bunx cap add android

Capacitor va créer les ios et android dossiers à la racine de votre projet contenant les projets natifs.

Pour compiler le projet Android, vous avez besoin d' Android Studio. Pour iOS, vous avez besoin d'un Mac avec Xcode.

Compilez et synchronisez votre projet :

bun run mobile

Ceci exécute votre script personnalisé qui génère le build statique Nuxt et synchronise les fichiers avec les plateformes natives.

Compiler et déployer des apps natives

Pour compiler et déployer votre application mobile native, suivez ces étapes :

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.

Ouvrez les projets natifs :

Pour iOS :

bun run mobile:ios

Pour Android :

bun run mobile:android

Ou directement avec Capacitor CLI :

bunx cap open ios
bunx cap open android

Compilez et lancez l'app :

Lancer sur Android Studio

Dans Android Studio, attendez que le projet soit prêt, puis cliquez sur le bouton « Run » pour déployer l'app sur un appareil connecté ou un émulateur.

Lancer sur Xcode

Dans Xcode, configurez votre compte de signature pour déployer l'app sur un appareil réel. Si vous ne l'avez jamais fait, Xcode vous guidera (notez que vous devez être inscrit au Apple Developer Program). Une fois configuré, cliquez sur le bouton « Play » pour lancer l'app sur votre appareil connecté.

Félicitations ! Vous avez déployé avec succès votre application web Nuxt sur un appareil mobile.

Mais attendez, il existe aussi un moyen plus rapide de faire cela pendant le développement…

Live Reload avec Capacitor

Pendant le développement, vous pouvez profiter du live reload pour voir vos modifications instantanément sur votre appareil mobile. Pour activer cette fonctionnalité, suivez ces étapes :

Trouvez votre adresse IP locale :

Sur macOS, exécutez la commande suivante dans le terminal :
```
ipconfig getifaddr en0
```
Sur Windows, lancez :
```
ipconfig
```
Cherchez l'adresse IPv4 dans la sortie.

Mettez à jour votre capacitor.config.ts pour pointer vers votre serveur de développement :

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... your plugin config
  },
};

export default config;

Remplacer YOUR_IP_ADDRESS avec votre adresse IP locale (ex. : 192.168.1.100).

Appliquez les modifications à votre projet natif :

bunx cap copy

Le copy La commande copie le dossier web et les modifications de configuration vers le projet natif sans mettre à jour tout le projet.

Lancez votre serveur de dev Nuxt et recompilez dans Xcode/Android Studio :

bun run dev

Désormais, chaque modification apportée à votre app Nuxt entraînera un rechargement automatique de l'app mobile pour refléter ces changements.

Note : Si vous installez de nouveaux plugins ou modifiez des fichiers natifs, vous devrez recompiler le projet natif, car le live reloading ne s'applique qu'aux changements de code web.

Utiliser les plugins Capacitor

Les plugins Capacitor vous permettent d'accéder aux fonctionnalités natives de l'appareil depuis votre application Nuxt. Explorons comment utiliser le plugin Share en guise d'exemple :

Installez le plugin Share :

bun add @capacitor/share

Créez ou mettez à jour une page pour utiliser le plugin Share. Dans Nuxt 4, les pages se trouvent dans app/pages/:

<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
    <button
      @click="shareContent"
      class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
    >
      Share now!
    </button>
  </div>
</template>

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

async function shareContent() {
  await Share.share({
    title: 'Check this out!',
    text: 'Built with Nuxt and Capacitor',
    url: 'https://capacitorjs.com',
    dialogTitle: 'Share with friends',
  });
}
</script>

Synchronisez les changements avec le projet natif :

bun run mobile

Ou synchronisez simplement sans reconstruire :

bunx cap sync

Reconstruisez et lancez l'app sur votre appareil.

Désormais, lorsque vous cliquez sur le bouton « Share now! », la boîte de dialogue de partage native s'affichera.

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.

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

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

@capgo/capacitor-native-navigation — une navbar native, une tab bar Liquid Glass sur iOS et un style de tab bar flouté sur Android. Votre routeur Nuxt 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 :

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

bun add -D tailwind-capacitor

Dans app/assets/css/main.css:

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

Pour Nuxt 4 avec Tailwind CSS 4, conservez cet import dans le fichier CSS référencé depuis nuxt.config.ts.

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 config Nuxt, 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 nuxt.config.ts, configurez le viewport via app.head:

export default defineNuxtConfig({
  app: {
    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,
#__nuxt {
  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: 'out',
  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

Vous avez converti avec succès votre application web Nuxt existante en applications natives iOS et Android grâce à Capacitor 8. Votre codebase Vue s'exécute désormais nativement sur les appareils mobiles avec un accès aux API de l'appareil.

Ce que vous avez accompli :

Configuration de Nuxt pour la génération statique
Ajout de Capacitor 8 avec les plugins essentiels
Compilation et déploiement sur les simulateurs iOS et Android
Activation du live reload pour le développement
Correction des problèmes de layout iOS courants (viewport, safe area, overflow)
Ajout d'une UI au rendu natif avec Capgo Native Navigation and Transitions

Prochaines étapes :

Configuration Capgo pour des live updates sans nouvelle soumission sur les stores
Ajouter d'autres plugins natifs comme Camera, Geolocation ou Push Notifications
Configurer les icônes et splash screens pour la production
Préparer votre app pour la publication sur l'App Store et Google Play

Vous lancez un nouveau projet ? Consultez Créer une application mobile Nuxt de zéro pour un tutoriel guidé.

Ressources

Documentation Nuxt
Capacitor 8 Documentation
@capgo/capacitor-native-navigation — barre d'onglets Liquid Glass et chrome natif
@capgo/capacitor-transitions — transitions de page au rendu natif
@capgo/tailwind-capacitor — Utilitaires Tailwind safe-area pour Capacitor
Capgo - Live Updates pour les apps Capacitor

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

Continuer depuis « Convertissez votre app Nuxt vers iOS et Android avec Capacitor 8 »

Si vous utilisez Convertissez votre app Nuxt en iOS et Android avec Capacitor 8 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.