Convertissez votre application Nuxt en iOS & Android avec Capacitor 8

Introduction

Disposez-vous d'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 avec Capgo Navigation et Transitions natives

Vous cherchez à démarrer un nouveau projet à partir de zéro ? Consultez notre guide sur Créer 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 mobile.
• 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 à travers les 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 d'applications
• Xcode (pour le développement iOS, macOS uniquement)
• Android Studio (pour le développement Android)

Configurer votre application Nuxt pour les appareils mobiles

La première étape consiste à configurer votre application Nuxt pour la génération statique. Capacitor nécessite des fichiers HTML/JS/CSS statiques pour les intégrer dans l'application native.

Assurez-vous que votre package.json 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 refacturer celles-ci 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 bundlera dans votre application native.

Ajouter Capacitor 8 à Votre Projet

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

1. Installez Capacitor core et CLI :

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

2. 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 de vie de l'application (avant-plan/arrière-plan, liens profonds)
• @capacitor/keyboard: Contrôler le comportement du clavier sur les appareils mobiles
• @capacitor/splash-screen: Gérer l'écran de splash natif
• @capacitor/status-bar: Personnaliser la barre d'état de l'appareil
• @capacitor/preferences: Stockage de valeurs clés (comme localStorage mais natif)

3. Initialisez Capacitor avec les détails de votre projet :

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

Remplacez my-app Avec votre nom d'application et com.example.myapp Avec votre ID d'application (notation de domaine inversée).

4. 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;

5. Installer les plateformes natives :

bun add @capacitor/ios @capacitor/android

6. Ajouter les dossiers de plateformes natives :

bunx cap add ios
bunx cap add android

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

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

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

Développement et déploiement d'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.

1. Ouvrir 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

2. Construire et exécuter l'application:

• 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 émulateur.

• 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 un moyen plus rapide de procéder pendant le développement…

Capacitor Live Reload

Pendant le développement, vous pouvez profiter de la mise à jour en temps réel pour voir les changements instantanément sur votre appareil mobile. Pour activer cette fonctionnalité, suivez ces étapes:

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

2. 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).

3. Appliquez les modifications à votre projet natif :

bunx cap copy

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

4. Démarrer votre serveur de développement Nuxt et rebuild 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 reconstruire le projet natif car la rechargement en temps réel 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 le plugin de partage en tant qu'exemple :

1. Installez le plugin de partage :

bun add @capacitor/share

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

3. Synchronisez les modifications avec le projet natif :

bun run mobile

Ou synchronisez simplement sans reconstruire :

bunx cap sync

4. Reconstruit et exécutez l'application sur votre appareil.

Maintenant, lorsque vous cliquez sur le bouton « Partagez maintenant ! », le dialogue de partage natif apparaitra.

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

UI native avec Capgo de navigation et de transitions natives

J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais intégrer Ionic 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-navigation-native — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Le 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 glissée vers l'arrière sur l'éditeur de iOS, sans adopter la UI Ionic.

Installez les deux :

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

Configurez la navigation native avec le mode d'insertion CSS 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 de tabs en verre liquide (iOS utilise la rendu système-propriétaire ; Android utilise un arrière-plan flou 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 des 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>

Enveloppez 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 lorsque la navigation native possède ces surfaces.

Consultez les guides complets : En utilisant @capgo/capacitor-native-navigation et En utilisant @capgo/capacitor-transitions.

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 le npm). Il fournit safe-areas des utilitaires et d'autres plugins Tailwind compatibles avec 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, gardez cette importation dans le fichier CSS référencé dans nuxt.config.ts.

Utilisez des utilitaires comme pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) par votre propre main. Le projet est actuellement développé — si quelque chose manque pour votre configuration Nuxt, ouvrir 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 déplaçable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster seul le tag de vueport ne suffit généralement pas. Travaillez à travers ces vérifications dans l'ordre.

Assurez-vous que le tag de métadonnées de vueport est appliqué correctement

Dans nuxt.config.ts, définissez la vueport par app.head:

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

Gérer la zone de sécurité iOS à partir d'un seul wrapper racine

Créez une coquille d'application unique et appliquez la mise en page de la zone de sécurité là-bas — 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 de .app-shellLe doublonnement de la mise en page de la zone de sécurité dans les en-têtes, les modaux et les enveloppes de mise en page de la disposition fait souvent que l'interface utilisateur semble coupée ou trop grande.

With @capgo/tailwind-capacitor, vous pouvez exprimer la même marge avec des utilitaires comme pt-safe pb-safe px-safe sur cette seule console.

Fixez Capacitor iOS contentInset à never premier

In capacitor.config.ts, préférez l'inset natif désactivé et laissez CSS (ou la navigation Native’s) contentInsetMode: 'css') posséder l'aire de sécurité :

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

Mélanger les inset de contenu automatique de Capacitor avec la mise en forme CSS env(safe-area-inset-*) est une cause courante de double espacement.

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

Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur en pixels fixe, ou un grand min-width.

En 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 de débordement horizontal proviennent de 100vw / w-screen, de la duplication de la marge de sécurité, ou d'un conteneur à largeur fixe — et non de la balise meta de la vue portée 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 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 des plugins essentiels
• Construit et déployé vers les simulateurs iOS et Android
• Activé le rechargement en direct pour le développement
• Corrigé les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement)
• Ajouté une interface utilisateur ressemblant à celle d'un système d'exploitation avec Capgo Navigation et Transitions natives

Étapes suivantes :

• Configurer Capgo pour les mises à jour hors ligne sans soumission à l'App Store
• Ajouter plus de plugins natives comme la Caméra, la géolocalisation ou les notifications Push
• Configurer les icônes et les écrans de démarrage de l'application pour la 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 présentation guidée.

Ressources

• Documentation Nuxt
• Capacitor 8 Documentation
• @capgo/capacitor-navigation-native — barre de navigation en verre liquide et navigateur natif
• @capgo/capacitor-transitions — transitions de page ressemblant à celles du navigateur natif
• @capgo/tailwind-capacitor — Utilités de zone de sécurité Tailwind pour Capacitor
• Capgo - Mises à jour en temps réel pour les applications Capacitor

Apprenez comment Capgo peut vous aider à construire des applications meilleures et plus rapides, s'inscrire à un compte gratuit aujourd'hui.

Continuez 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-le avec Répertoire de plugins Capgo pour le flux de travail du produit dans le Répertoire de plugins Capgo Plugins Capacitor par Capgo for the implementation detail in Capacitor Plugins by Capgo, Ajouter ou Mettre à Jour les Plugins Détails d'implémentation dans Ajouter ou Mettre à Jour les Plugins, Alternatives aux Plugins Entreprise Ionic Détails du flux de travail du produit dans Alternatives aux Plugins Entreprise Ionic, et Détails du flux de travail du produit dans Capgo Native Builds. for the product workflow in Capgo Native Builds.