Introduction
Avez-vous une application web Nuxt existante ? Dans ce guide, vous apprendrez à transformer celle-ci en applications mobiles natives iOS et Android à l'aide de Capacitor __CAPGO_KEEP_0__
Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.
__CAPGO_KEEP_0__ 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 __CAPGO_KEEP_1__ fonctionne tel quel.
- Ce que vous allez apprendre :
- Add Capacitor 8 with essential native plugins
- Ajouter __CAPGO_KEEP_0__ 8 avec les plugins natifs essentiels
- Construire et tester sur les simulateurs iOS et Android
- Activer la rechargement en direct pour une mise au point plus rapide
- Add native-feeling UI with Capgo Native Navigation and Transitions
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 Reusabilité: Partagez vos composants Vue et votre logique entre les applications web et mobile.
- Performancescontext : Page/zone : Section d'aide pour les problèmes et les solutions. Rôle : En-tête de section ou de page. Vu dans : page premium-support.astro. Message clé `ps_help_performance_title` (Ps Help Performance Title).
- : La génération statique de Nuxt crée des bundles optimisés parfaits pour les appareils mobiles.: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
- : Accédez aux fonctionnalités de l'appareil comme la caméra, la géolocalisation et le système de fichiers à l'aide de __CAPGO_KEEP_0__ plugins.Développement simplifié
: Utilisez des modèles Vue/Nuxt familiers sans avoir besoin d'apprendre le développement natif.
Avant de commencer, assurez-vous d'avoir :
- Node.js 18+ installé
- Un projet existant Nuxt 4 une 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 possède 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 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 emballera dans votre application native.
Capacitor 8 dans 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/preferencesCes plugins fournissent des fonctionnalités essentielles :
- @capacitor/app: Gérer les événements de cycle d'applications (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 démarrage natif
- @capacitor/status-bar: Personnaliser la barre d'état de l'appareil
- @capacitor/preferences: Stockage de valeurs clés-valeurs (comme localStorage mais natif)
- Initialiser Capacitor avec les détails de votre projet :
bunx cap init my-app com.example.myapp --web-dir .output/publicRemplacer my-app avec votre nom d'application et com.example.myapp avec votre ID d'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 plateformes natives :
bunx cap add ios
bunx cap add androidCapacitor 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 StudioPour 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.
La construction et la mise en ligne 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.
- Ouvrez les projets natives :
Pour iOS :
bun run mobile:iosFor Android :
bun run mobile:androidOu directement avec Capacitor CLI :
bunx cap open ios
bunx cap open android- 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 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 dans le programme Apple Developer). Une fois configuré, cliquez sur le bouton « Play » 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 effectuer cela 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.
- Mettez à jour votre
capacitor.config.tspour qu'elle 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 copyLa copy commande copie le dossier web et les modifications de configuration vers le projet natif sans mettre à jour l'ensemble du projet.
- Démarrer votre serveur de développement Nuxt et rebuild dans Xcode/Android Studio :
bun run devNow, every time you make changes to your Nuxt app, the mobile app will automatically reload to reflect those changes.
Remarque : If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.
Using 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 : Créez ou mettez à jour une page pour utiliser le plugin de partage. Dans Nuxt 4, les pages se trouvent dans
- Synchronisez les modifications avec le projet natif :
bun add @capacitor/share- Ou synchronisez sans reconstruire :
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>- Reconstruirez et exécutez l'application sur votre appareil.
bun run mobileRebuild and run the app on your device.
bunx cap sync- Reconstruirez et exécutez l'application sur votre appareil.
Now, when you click the “Cliquez maintenant sur le bouton” button, the native share dialog will appear.
Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.
Native-feeling UI with Capgo Native Navigation and Transitions
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 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, barre de Liquid Glass 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 fenêtre native.
- @capgo/capacitor-transitions — transitions de page à la manière d'Ionic et swipe-back sur l'édge sur iOS dans la couche WebView, sans adopter l’UI 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 de tabs en verre liquide (iOS utilise la mise en page système ; Android utilise un fond de fenêtre WebView flou) :
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>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 lorsque la navigation native en a la charge.
Consultez les guides complets : Utiliser @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.
Zones de sécurité avec Tailwind
Pour les zones de sécurité de l'appareil dans Tailwind CSS, utilisez @capgo/tailwind-capacitor paru sous tailwind-capacitor sur npm). Il fournit safe-areas outils et autres plugins de Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorDans 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-*) par votre propre main. Le projet est actuellement développé — si quelque chose manque pour votre configuration Nuxt, ouvrir un PR sur GitHub.
Fixer 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 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 le tag meta de vueport est appliqué correctement
In 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-y la mise en page de la zone de sécurité — 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 modales et les enveloppes de mise en page peut rendre l'interface utilisateur 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 coquille.
Fixez Capacitor iOS contentInset à never context : Page/zone : Page de produits de mise à jour en temps réel. Rôle : Étiquette de l'interface utilisateur courte ou élément de navigation. Clé de message `live_update_dynamic_label_to` (Étiquette dynamique de mise à jour en temps réel).
premier capacitor.config.tsDans contentInsetMode: 'css', préférez l'inset natif désactivé et laissez CSS (ou la navigation native)
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-*) Mélanger les inset automatiques de contenu de __CAPGO_KEEP_0__ avec CSS
Trouvez l'élément débordant réel
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur de pixels fixe, ou une large min-width.
Inspécteur Web 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,
}));Avec Tailwind, remplacez w-screen par w-full lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, une duplication de la marge de sécurité, ou un conteneur à largeur fixe — et non de la balise meta de la vue d'ensemble elle-même.
Conclusion
Vous avez réussi à convertir votre application web Nuxt existante 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
- 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 (vueport, zone de sécurité, débordement)
- Added une interface utilisateur ressemblant à celle des appareils natifs avec Capgo Navigation et Transitions Native
É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
Vous commencez 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 Liquid Glass et chrome natif
- @capgo/capacitor-transitions — transitions de page ressemblant à celles d'un navigateur
- @capgo/tailwind-capacitor --- Utilitaires de zone de sécurité de 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 à planifier le travail de 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 Ajouter ou Mettre à Jour les Plugins pour les détails d'implémentation dans Ajouter ou Mettre à Jour les Plugins Alternatives aux Plugins Entreprise d'Ionic pour le flux de travail du produit dans Alternatives aux Plugins Entreprise d'Ionic, et Capgo Builds Natives pour le flux de travail du produit dans Capgo Builds Natives.
