Convertissez votre application Nuxt en iOS & Android avec Capacitor 8

Introduction

Vous avez une application web Nuxt existante ? Dans ce guide, vous apprendrez à la transformer en applications mobiles natives iOS et Android en utilisant Capacitor 8 — la dernière version avec une meilleure performance 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 codebase Vue existant. Contrairement à Flutter ou React Native, vous n'avez pas besoin de réécrire quoi que ce soit — votre Nuxt code fonctionne tel quel.

Ce que vous allez apprendre :

Configurez votre application Nuxt existante pour la génération statique
Ajoutez Capacitor 8 avec les plugins natifs essentiels
Construisez et testez sur les simulateurs iOS et Android
Activez la reprise en direct pour un développement plus rapide
Corrigez les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement horizontal)
Ajoutez une interface utilisateur ressemblant à celle des appareils natifs avec Capgo Navigation et Transitions natifs

Vous souhaitez démarrer un nouveau projet à partir de zéro ? Consultez notre guide sur La création d'une application mobile Nuxt à partir de zéro.

Avantages de l'utilisation de Nuxt et Capacitor

Code Reutilisation: Partagez vos composants Vue et votre logique entre les applications web et mobiles.
Performance: La génération statique de Nuxt crée des bundles optimisés parfaits pour les appareils mobiles.
Capacités natives: Accédez aux fonctionnalités de l'appareil comme la caméra, la géolocalisation et le système de fichiers à l'aide des plugins Capacitor.
Développement simplifié: Utilisez les modèles familiers Vue/Nuxt sans avoir besoin d'apprendre le développement natif.

Prérequis

: Avant de commencer, assurez-vous d'avoir :

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

Configuration de votre application Nuxt pour les appareils mobiles

Le premier pas consiste à configurer votre application Nuxt pour la génération statique. Capacitor nécessite des fichiers HTML/JS/CSS statiques pour les assembler dans l'application native.

Assurez-vous que votre package.json context : fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `solutions_cordova_to_capacitor_ai_step2_body`). Page/zone : page de marketing de solutions Capgo. Rôle : phrase de copie du site web. Vu dans : page solutions/cordova-to-capacitor-ai.astro. Clé de message `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body).

{
  "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"
  }
}

a le script de génération : If you’re using server-side features (API routes, server middleware, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

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 emballera dans votre application native.

Ajouter Capacitor 8 à votre projet

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

Installez Capacitor core et CLI :

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

Installez les plugins Capacitor courants que vous aurez probablement besoin :

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

Ces plugins fournissent des fonctionnalités essentielles :

@capacitor/app: Gérer les événements de cycle d'application (avant-plan/arrière-plan, liens profonds)
@capacitor/keyboard: Contrôler le comportement de la touche sur mobile
@capacitor/écran d'accueil: Gérer l'écran d'accueil natif
@capacitor/barre d'état: Personnaliser la barre d'état du dispositif
@capacitor/préférences: Stockage de valeurs clés (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

Remplacez my-app par le nom de votre application et com.example.myapp par 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 de la plateforme native :

bunx cap add ios
bunx cap add android

Capacitor créera ios et android des dossiers au niveau de votre projet contenant les projets natifs.

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

Construire et synchroniser votre projet :

bun run mobile

Cela exécute votre script personnalisé qui génère la mise en page statique Nuxt et synchronise les fichiers avec les plateformes natives.

Construire et Déployer des Applications Natives

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

Pour développer des applications iOS, vous devez avoir Xcode installé, et pour les applications Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez de distribuer votre application sur l'App Store, vous devez vous inscrire au programme Apple Developer pour iOS et au 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

Construirez et exécutez l'application :

android-studio-run

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

xcode-run

Dans Xcode, configurez votre compte de signature pour déployer l'application sur un appareil réel. Si vous n'avez pas déjà effectué cela, Xcode vous guidera tout au long du processus (notez que vous devez être inscrit dans le programme Apple Developer). Une fois configuré, cliquez sur le bouton « Jouer » pour exécuter l'application sur votre appareil connecté.

Félicitations ! Vous avez réussi à déployer votre application web Nuxt sur un appareil mobile.

Mais attendez, il existe également une méthode plus rapide pour procéder pendant le développement…

Capacitor Live Reload

En développement, vous pouvez profiter de la rechargement en direct pour voir les changements instantanément sur votre appareil mobile. Pour activer cette fonctionnalité, suivez ces étapes :

Trouvez votre adresse IP locale :

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

Mettre à jour votre capacitor.config.ts pour qu'il pointe 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;

Remplacez YOUR_IP_ADDRESS par votre adresse IP locale (par exemple, 192.168.1.100).

Appliquez les modifications à votre projet natif :

bunx cap copy

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

Démarrer votre serveur de développement Nuxt et reconstruire dans Xcode/Android Studio :

bun run dev

Maintenant, chaque fois que vous faites des modifications à votre application Nuxt, l'application mobile se rechargera automatiquement pour refléter ces modifications.

Remarque : Si vous installez de nouveaux plugins ou faites des modifications à des fichiers natifs, vous devrez reconstruire le projet natif car la rechargement en temps réel ne s'applique qu'aux modifications web code.

Utilisation des Capacitor Plugins

Les plugins Capacitor vous permettent d'accéder aux fonctionnalités du dispositif natif depuis votre application Nuxt. Explorons comment utiliser le Le plugin Partager comme exemple :

Installez le plugin Partager :

bun add @capacitor/share

Créez ou mettez à jour une page pour utiliser le plugin Partager. 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 modifications avec le projet natif :

bun run mobile

Ou synchronisez simplement sans reconstruire :

bunx cap sync

Reconstruirez et exécutez l'application sur votre appareil.

Maintenant, lorsque vous cliquez sur le bouton « Partager maintenant ! », le dialogue de partage natif s'affichera.

Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec les Capgo navigation et transitions, et corriger les problèmes de mise en page iOS courants qui entraînent un débordement horizontal ou des zones de sécurité coupées.

J'ai travaillé pendant des années avec Ionic pour construire des applications plate-forme croisée, mais l'intégration avec Nuxt est hacky et rarement valable lorsque vous avez déjà Tailwind CSS.

Pour un sentiment mobile natif dans une application Nuxt + Capacitor, utilisez les plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :

@capgo/capacitor-native-navigation — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur Nuxt conserve l'état de la route ; le plugin possède la barre de chrome native.
@capgo/capacitor-transitions — transitions de page Ionic et iOS swipe-back sur l'arrière de l'écran 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',
  },
});

Rendre une barre de tab Liquid Glass (iOS utilise la mise en page système ; Android utilise un arrière-plan flou de WebView) :

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 les transitions de page natives dans votre coquille d'application :

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

Wrap les pages routées dans cap-router-outlet, cap-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant de naviguer. N'ajoutez pas de titres ou de pieds de page web lorsqu'une navigation native contrôle ces surfaces.

Voir les guides complets : Utiliser @capgo/capacitor-navigation-native et Utiliser @capgo/capacitor-transitions.

Les zones de sécurité avec Tailwind

Pour les zones de sécurité des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas des outils et d'autres plugins Capacitor-compatibles Tailwind :

bun add -D tailwind-capacitor

In 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, gardez cette importation dans le fichier CSS référencé depuis nuxt.config.ts.

Utilisez des outils comme pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration Nuxt, ouvre une PR sur GitHub.

Résoudre les problèmes de disposition iOS (Vueport, Zone de sécurité, et Débordement horizontal)

Si le contenu semble coupé, décalé ou déroulable horizontalement sur iOS, ajoutez plus overflow-x: hidden ou encore ajuster la balise viewport seule ne résout généralement pas le problème. Effectuez ces vérifications dans l'ordre.

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

Dans nuxt.config.tsappliquez la vueports via app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

Gérez l'espace sûr d'iOS à partir d'un seul wrapper racine.

Créez une coquille d'application unique et appliquez-y le padding de l'espace sûr — et non 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 à l'intérieur .app-shell. Le padding de l'espace sûr répété dans les en-têtes, les modaux et les enveloppes de mise en page peut rendre l'interface utilisateur coupée ou trop grande.

Avec @capgo/tailwind-capacitorvous pouvez exprimer le même padding avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.

Configurez Capacitor iOS `contentInset` à `never` premier

Dans capacitor.config.ts, préférez les espaces insérés natifs désactivés et laissez CSS (ou Native Navigation’s) contentInsetMode: 'css') gérer l'espace sûr :

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

Mélanger les espaces insérés automatiques de Capacitor avec CSS env(safe-area-inset-*) la marge est une cause courante de double espace.

Trouvez l'élément qui déborde vraiment

L'élément coupable est généralement un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou un grand min-width.

In Safari Web Inspector, exécutez :

[...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 lorsque possible. De nombreux problèmes d'écoulement horizontal proviennent de 100vw / w-screenune duplication de la marge de sécurité de zone sûre, ou d'un conteneur de largeur fixe — et non de la balise meta de la zone de visualisation elle-même.

Conclusion

Vous avez réussi à convertir votre application web existante Nuxt en applications natives iOS et Android à l'aide de Capacitor 8. Votre code Vue est maintenant exécuté nativement sur les appareils mobiles avec accès aux API de l'appareil.

Ce que vous avez accompli :

Configuré Nuxt pour la génération statique
Added Capacitor 8 avec les plugins essentiels
Construit et déployé vers les simulateurs iOS et Android
Activé la reprise en direct pour le développement
Résolu les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement)
Added native-feeling UI with Capgo Native Navigation and Transitions

Étapes suivantes :

Configurer Capgo pour les mises à jour hors ligne sans résubmission de l'application sur l'App Store
Ajoutez plus de plugins natifs comme la caméra, la géolocalisation ou les notifications Push
Configurez les icônes d'application et les écrans de démarrage pour la production
Préparez votre application pour la soumission sur l'App Store et Google Play

Démarrer un nouveau projet ? Consultez Construire une application mobile Nuxt à partir de zéro pour une prise en main guidée.

Ressources

Documentation Nuxt
Capacitor 8 Documentation
@capgo/capacitor-navigation-native — Barre de navigation Liquid Glass et navigateur natif
@capgo/capacitor-transitions — Transitions de page ressemblant à celles d'un navigateur natif
@capgo/tailwind-capacitor — Utilitaires de zone sûre Tailwind pour Capacitor
Capgo - Mises à jour en temps réel pour les applications Capacitor

Apprenez comment Capgo peut vous aider à créer des applications meilleures et plus rapides, inscrivez-vous pour un compte gratuit Aujourd'hui.

Continuez à partir de Convertir votre application Nuxt en iOS & Android avec Capacitor 8

Si vous utilisez Convertir votre application Nuxt en iOS & Android avec Capacitor 8 Pour planifier le travail du plugin natif, connectez-l’avec Capgo Répertoire des plugins pour le flux de travail du produit dans Capgo Répertoire des plugins Capacitor Plugins par Capgo pour les détails d'implémentation dans Capacitor Plugins par Capgo Ajout ou mise à jour de plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins Alternatives aux plugins d'entreprise Ionic pour le flux de travail du produit dans les alternatives Ionic Enterprise Plugin, et Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs.

Convertissez votre application Nuxt en applications mobiles iOS et Android avec Capacitor 8

Introduction

Avantages de l'utilisation de Nuxt et Capacitor

Prérequis

Configuration de votre application Nuxt pour les appareils mobiles

Ajouter Capacitor 8 à votre projet

Construire et Déployer des Applications Natives

Capacitor Live Reload

Utilisation des Capacitor Plugins

Interface utilisateur ressemblant à celle d'un appareil natif avec les Capgo Navigation et Transitions

Les zones de sécurité avec Tailwind

Résoudre les problèmes de disposition iOS (Vueport, Zone de sécurité, et Débordement horizontal)

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

Gérez l'espace sûr d'iOS à partir d'un seul wrapper racine.

Configurez Capacitor iOS `contentInset` à `never` premier

Trouvez l'élément qui déborde vraiment

Conclusion

Ressources

Continuez à partir de Convertir votre application Nuxt en iOS & Android avec Capacitor 8

Convertissez votre application Nuxt en applications mobiles iOS et Android avec Capacitor 8

Introduction

Avantages de l'utilisation de Nuxt et Capacitor

Prérequis

Configuration de votre application Nuxt pour les appareils mobiles

Ajouter Capacitor 8 à votre projet

Construire et Déployer des Applications Natives

Capacitor Live Reload

Utilisation des Capacitor Plugins

Interface utilisateur ressemblant à celle d'un appareil natif avec les Capgo Navigation et Transitions

Les zones de sécurité avec Tailwind

Résoudre les problèmes de disposition iOS (Vueport, Zone de sécurité, et Débordement horizontal)

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

Gérez l'espace sûr d'iOS à partir d'un seul wrapper racine.

Configurez Capacitor iOS contentInset à never premier

Trouvez l'élément qui déborde vraiment

Conclusion

Ressources

Continuez à partir de Convertir votre application Nuxt en iOS & Android avec Capacitor 8

Configurez Capacitor iOS `contentInset` à `never` premier