Convertissez votre application Nuxt en iOS & Android avec Capacitor 8

Introduction

Avez-vous 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 apprendrez :

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
Enable live reload for faster development
Réparez les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement horizontal)
Add native-feeling UI with Capgo Native Navigation and Transitions

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.
Performances: La génération statique de Nuxt crée des bundles optimisés parfaits pour les appareils mobiles.
Capacités nativesAccédez aux fonctionnalités du dispositif comme la caméra, la géolocalisation et le système de fichiers à travers les plugins Capacitor.
Développement simplifié: Utiliser les modèles familiers Vue/Nuxt sans apprendre le développement natif.

Prerequisites

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

Configuring Your Nuxt App for Mobile

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 regrouper dans l'application native.

Assurez-vous que votre package.json a a le script de génération :

{
  "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 de serveur, etc.), vous devrez les réécrire 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 rassemblera dans votre application native.

Ajouter Capacitor 8 à votre projet

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

Initialiser Capacitor avec les détails de votre projet :

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

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

Créer ou mettre à 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;

Installer les plateformes natives :

bun add @capacitor/ios @capacitor/android

Ajoutez les dossiers de plateforme native :

bunx cap add ios
bunx cap add android

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

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 Mobiles

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

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

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

run-xcode

Configurez votre compte de signature dans Xcode 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 :

Sur macOS, exécutez la commande suivante dans le terminal :
```
ipconfig getifaddr en0
```
Sur Windows, exécutez :
```
ipconfig
```
Recherchez 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;

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 La 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 rebuildir dans Xcode/Android Studio :

bun run dev

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

Remarque : Si vous installez de nouveaux plugins ou apportez des modifications à des fichiers natifs, vous devrez rebuildir le projet natif car la rechargement en direct ne s'applique qu'aux modifications web code.

Utilisation des Capacitor Plugins

Les Capacitor plugins vous permettent d'accéder aux fonctionnalités de votre appareil mobile depuis votre application Nuxt. Explorons comment utiliser les Partager plugin par exemple :

Installez le plugin Partager :

bun add @capacitor/share

Créez ou mettez à jour une page pour utiliser le plugin Partage. 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>

Synchronez les modifications avec le projet natif :

bun run mobile

Ou synchronez simplement sans reconstruire :

bunx cap sync

Reconstruit 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 la navigation et les transitions Capgo 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 multiplateformes, mais l'intégrer avec Nuxt est hacky et rarement valable lorsque vous avez déjà Tailwind CSS.

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

@capgo/capacitor-navigation-native — 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 gère la barre de chrome native.
@capgo/capacitor-transitions — Transition de page à l'Ionic et swipe-back sur l'edge 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',
  },
});

Afficher une barre d'onglets Liquid Glass (iOS utilise la mise en page système ; Android utilise un fond flou d'une fenêtre 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}`);
});

Add native page transitions in your 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-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') Avant de naviguer. N'ajoutez pas de titres ou de pieds de page web si la navigation native les gère.

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

Aires sûres avec Tailwind

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

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 mise en page iOS (Vueport, Zone de sécurité et débordement horizontal)

Si le contenu semble coupé, décalé ou scrollable horizontalement sur iOS, ajouter plus de overflow-x: hidden ou modifier seul le tag de viewport ne résout généralement pas le problème. Passer par ces vérifications dans l'ordre.

Vérifiez que la balise meta viewport est appliquée correctement

Dans nuxt.config.ts, définissez la vue par défaut 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 un noyau d'application unique et appliquez une marge de zone de sécurité là-bas — 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);
}

Wrappez tout le contenu de la page à l'intérieur .app-shellLes marges de sécurité dupliquées dans les en-têtes, les modaux et les enveloppes de mise en page rendent souvent l'interface utilisateur coupée ou trop grande.

Avec @capgo/tailwind-capacitor, vous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.

Définissez Capacitor iOS `contentInset` vers `never` premier

En capacitor.config.tspréférez l'insérer nativement désactivé et laissez CSS (ou la navigation native) contentInsetMode: 'css'Propriétaire de la zone de sécurité :

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

Mélanger les Capacitor automatiques d'encart de contenu avec CSS env(safe-area-inset-*) L'élément coupable est généralement un élément utilisant

Trouvez l'élément qui déborde réellement

, une largeur fixe en pixels, ou une large 100vw, Tailwind w-screenune largeur de pixels fixe, ou une large min-width.

Dans l'inspecteur Web de Safari, 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,
  }));

En utilisant Tailwind, remplacez w-screen par w-full lorsque possible. De nombreux problèmes d'écoulement horizontal proviennent de 100vw / w-screenPas de padding de zone de sécurité dupliquée, ni d'un conteneur à largeur fixe — pas de la balise meta viewport elle-même.

Conclusion

Vous avez réussi à convertir votre application web existante Nuxt en applications natives iOS et Android en utilisant Capacitor 8. Votre code Vue fonctionne maintenant 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
Ajouté Capacitor 8 avec les plugins essentiels
Construit et déployé vers les simulateurs iOS et Android
Enabled live reload for development
Résolu les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement)
UI native ressentant avec Capgo Navigation et Transitions natifs ajoutés

Étapes suivantes :

Configurer Capgo pour les mises à jour hors ligne sans réévaluation de l'App Store
Ajoutez plus de plugins natifs comme la Caméra, la Géolocalisation ou les Notifications Push
Configure app icons and splash screens for production
Préparez votre application pour la soumission sur l'App Store et Google Play

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

Ressources

Nuxt Documentation
Capacitor 8 Documentation
@capgo/capacitor-navigation-native — barre de tab de verre liquide et navigateur natif
@capgo/capacitor-transitions — transitions de page ressenties comme natif
@capgo/tailwind-capacitor — utilitaires de zone sûre de Tailwind pour Capacitor
Capgo - Live Updates for Capacitor Apps

Learn how Capgo can help you build better apps faster, inscrivez-vous à 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 de plugin natif, connectez-l’à 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 de plugins d'entreprise Ionic pour le flux de travail du produit dans les alternatives du plugin Enterprise Ionic Capgo Native Builds pour le flux de travail du produit dans Capgo Builds natifs.