Introduction
Avez-vous une application web Nuxt existante ? Dans ce guide, vous apprendrez comment 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
- Construire et tester sur les simulateurs iOS et Android
- Activer la reprise de vie pour un développement plus rapide
- Résoudre les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement horizontal)
- Ajouter une interface utilisateur ressemblant à celle des natives avec Capgo Navigation et Transitions Native
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 ReutilisationPartagez 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 natives: Accédez aux fonctionnalités de l'appareil comme la caméra, la géolocalisation et le système de fichiers à travers les Capacitor plugins.
- Simplification du Développement: Utilisez des modèles Vue/Nuxt familiers sans avoir besoin d'apprendre le développement natif.
Prérequis
Avant de commencer, assurez-vous d'avoir :
- Node.js 18+ installé
- Une application Nuxt 4 existante
- Xcode (pour le développement iOS, macOS uniquement)
- Android Studio (pour le développement Android)
Configurer 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 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 generateVous devriez voir un .output/public dossier contenant vos fichiers statiques. C'est ce que Capacitor assemblera dans votre application native.
Intégrer Capacitor 8 à votre projet
Pour empaqueter votre application Nuxt dans un conteneur mobile natif, suivez ces étapes :
- Installez le noyau Capacitor 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/preferencesCes 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 de la touche sur mobile
- @capacitor/splash-screen : Gérer l'écran de splash natif
- @capacitor/status-bar : Personnaliser la barre d'état du dispositif
- @capacitor/préférencesStockage 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/publicRemplacez 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.tsfichier 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 androidCapacitor créera ios et android dossiers à la racine 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 mobileCela exécute votre script personnalisé qui génère la mise en page statique Nuxt et synchronise les fichiers avec les plateformes natives.
Développer et Déployer des Applications Mobiles 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 est 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:iosPour Android :
bun run mobile:androidOu directement avec Capacitor CLI:
bunx cap open ios
bunx cap open android- Déployez et exécutez 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 un é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 au 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.
Attends une minute, il existe une méthode plus rapide pour procéder pendant le développement…
Capacitor Live Reload
Pendant le 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 :
ipconfigRecherchez l'adresse IPv4 dans la sortie.
- Mettriez à jour votre
capacitor.config.tspour 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 copyLa copy commande copie le dossier web et les modifications de configuration dans le projet natif sans mettre à jour l'ensemble du projet.
- Démarrer votre serveur de développement Nuxt et reconstruire dans Xcode/Android Studio :
bun run devMaintenant, 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 plugin de partage comme exemple :
- Installez le plugin de partage :
bun add @capacitor/share- 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>- Synchronisez les modifications avec le projet natif :
bun run mobileOu synchronisez simplement sans reconstruire :
bunx cap sync- Reconstruirez et exécutez l'application sur votre appareil.
Maintenant, lorsque vous cliquez sur le bouton « Partagez maintenant ! », le dialogue de partage natif s'affichera.
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec Capgo de la navigation et des 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.
Interface utilisateur ressemblant à une application native avec Capgo de la navigation et des transitions natives
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais l'intégration avec Nuxt est hacky et rarement valable lorsque vous avez déjà Tailwind CSS.
Pour un sentiment de mobilité natif dans une application Nuxt + Capacitor , utilisez les Capgo plugins au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation native — une barre de navigation native, une barre d'onglets Liquid Glass sur iOS, et un style de barre d'onglets flou sur Android. Votre routeur Nuxt conserve l'état des routes ; le plugin gère la barre d'application native.
- @capgo/capacitor-transitions — des transitions de page à la manière d'Ionic et un retour arrière par swipe sur l'écran sur iOS, sans adopter l'interface utilisateur d'Ionic.
Installez les deux :
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurez 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 d'onglets Liquid Glass (iOS utilise la mise en page système ; Android utilise un fond flou de la couche 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 appelez cap-contentou setDirection('forward') or 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 : En utilisant @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.
Aires sûres avec Tailwind
Pour les zones sûres des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas des utilitaires et d'autres plugins Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorIn app/assets/css/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";For Nuxt 4 avec Tailwind CSS 4, gardez cette importation dans le fichier CSS référencé de nuxt.config.ts.
Utilisez des utilitaires comme pt-safe, pb-safe, et px-safe au lieu de les ajouter env(safe-area-inset-*) manuellement. Le projet est actuellement en développement — si quelque chose manque pour votre configuration Nuxt, ouvre une PR sur GitHub.
Résoudre les problèmes de disposition sur 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 ajuster seul le tag de vueport ne résout généralement pas le problème. Travaillez à travers ces vérifications dans l'ordre.
Assurez-vous que la balise meta de vueport est appliquée correctement
Dans nuxt.config.ts, définissez la vueport par le biais de app.head:
export default defineNuxtConfig({
app: {
head: {
meta: [
{
name: 'viewport',
content: 'width=device-width, initial-scale=1, viewport-fit=cover',
},
],
},
},
});Gérer l'espace sûr iOS à partir d'un seul enveloppe racine
Créez un seul coquille d'application et appliquez la mise en forme de l'espace sûr là — 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 à l'intérieur .app-shell. La mise en forme de l'espace sûr dupliquée dans les en-têtes, les modales et les enveloppes de disposition rend 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 seule coquille.
Définissez Capacitor iOS contentInset sur never premier
En capacitor.config.tspréférez l'insérer natif désactivé et laissez CSS (ou la navigation native) gérer l'espace sûr : contentInsetMode: 'css'Mélanger l'insérer automatique de contenu de __CAPGO_KEEP_0__ avec CSS
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trouvez l'élément qui déborde vraiment
L'élément habituel coupable est un élément utilisant
, Tailwind 100vw, une largeur fixe en pixels, ou une large w-screenDans l'inspecteur Web de Safari, exécutez : min-width.
Avec Tailwind, remplacez
[...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,
}));par w-screen lorsque possible. De nombreux problèmes de débordement horizontal proviennent de w-full when possible. Many horizontal overflow issues come from 100vw / w-screenou des marges de zone de sécurité redondantes, ou un conteneur de largeur fixe — pas de la balise meta de la vue portative 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 s'exécute 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
- Added Capacitor 8 avec les 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 (vue portative, zone de sécurité, débordement)
- Added une interface utilisateur ressemblant à celle d'un appareil natif avec Capgo Navigation Native et 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 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
En créant une nouvelle application ? 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 Liquid Glass et navigateur natif
- @capgo/capacitor-transitions — Transitions de page ressemblant à celles d'un navigateur natif
- @capgo/tailwind-capacitor — Utilitaires de zone de sécurité Tailwind pour Capacitor
- Capgo - Mises à jour en temps réel pour les applications Capacitor
Découvrez comment Capgo peut vous aider à créer 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 planer le travail de plugin natif, le connecter avec Capgo Répertoire de Plugin pour le flux de travail du produit dans Capgo Répertoire de Plugin, Capacitor Plugins par Capgo pour les détails d'implémentation dans Capacitor Plugins par Capgo, Ajouter ou Mettre à Jour les Plugins pour les détails d'implémentation dans Ajouter ou Mettre à Jour les Plugins, Alternatives de Plugin Entreprise Ionic pour le flux de travail du produit dans Alternatives de Plugin Entreprise Ionic, et Capgo Bâtiments Natives pour le flux de travail du produit dans Capgo Bâtiments Natives.
