Créez une application mobile Nuxt à partir de zéro avec Capacitor 8

Introduction

Vous souhaitez créer une application mobile avec Nuxt à partir de zéro ? Ce guide vous accompagne dans la création d'un projet Nuxt 4 entièrement configuré pour les appareils mobiles dès le départ, puis dans l'emballage de celui-ci sous forme d'applications natives iOS et Android à l'aide de Capacitor 8.

À la fin de ce tutoriel, vous disposerez d'une application mobile fonctionnelle exécutée sur des simulateurs que vous pourrez continuer à développer et publier ultérieurement sur l'App Store et Google Play.

Temps requis : ~30 minutes

Ce que vous construisez :

• Un nouveau projet Nuxt 4 avec la structure de répertoire la plus récente
• La configuration de la génération statique pour les appareils mobiles
• Capacitor 8 with essential plugins
• Les applications natives iOS et Android
• Un environnement de développement avec rechargement en direct

Vous avez déjà une application Nuxt ? Consultez Convertissez votre application Nuxt en application mobile au lieu de cela.

Prérequis

Assurez-vous d'avoir ces éléments installés :

• Node.js 18+ (vérifiez avec node --version)
• Bun gestionnaire de packages (curl -fsSL https://bun.sh/install | bash)
• Xcode (seulement pour macOS, pour le développement iOS)
• Android Studio (pour le développement Android)

Étape 1 : Créez un nouveau projet Nuxt 4

Commencez par créer un projet Nuxt 4 frais :

bunx nuxi@latest init my-mobile-app
cd my-mobile-app
bun install

Structure de répertoire de Nuxt 4

Nuxt 4 utilise une nouvelle structure de répertoire avec l'application code dans le app/ répertoire :

my-mobile-app/
  app/
    assets/
    components/
    composables/
    layouts/
    middleware/
    pages/
    plugins/
    utils/
    app.vue
  public/
  server/
  nuxt.config.ts
  package.json

Cette structure fournit une meilleure séparation entre l'application et le serveur code.

Étape 2 : Configurez Nuxt pour la génération statique

Capacitor nécessite des fichiers HTML/JS/CSS statiques. Configurez Nuxt pour la génération statique dans nuxt.config.ts:

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  // Enable static generation
  ssr: true,
  nitro: {
    preset: 'static',
  },
});

Étape 3 : Ajoutez les scripts mobiles

Mettez à jour votre package.json avec les scripts de développement mobile :

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

Testez la génération statique :

bun run generate

Vous devriez voir un .output/public répertoire avec vos fichiers statiques.

Étape 4 : Installez Capacitor 8

Installez les packages de base de Capacitor :

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

Installez les plugins essentiels dont la plupart des applications mobiles ont besoin :

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

Ce que font ces plugins :

• @capacitor/app — Événements de cycle de vie de l'application (avant-plan/arrière-plan, liens profonds)
• @capacitor/keyboard — Contrôle du comportement de la touche clavier
• @capacitor/splash-screen — Contrôle de l'écran de démarrage natif
• @capacitor/status-bar — Personnalisez la barre d'état du dispositif
• @capacitor/preferences — Stockage de valeurs clés (comme localStorage mais natif)

Étape 5 : Initialisez Capacitor

Initialisez Capacitor avec vos détails de projet :

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir .output/public

Remplacez :

• "My Mobile App" par le nom de votre application
• com.example.mymobileapp par l'ID de votre application (notation de domaine inversé)

Cela crée capacitor.config.tsMettez à jour avec la configuration du plugin :

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile 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;

Étape 6 : Ajouter les plateformes natives

Installez les packages de plateforme :

bun add @capacitor/ios @capacitor/android

Générez les projets natifs :

bunx cap add ios
bunx cap add android

Cela crée ios et android des répertoires contenant les projets natifs.

Étape 7 : Construire et Exécuter

Construire votre projet et synchroniser avec les plateformes natives :

bun run mobile

Ouvrir dans l'émulateur iOS :

bun run mobile:ios

Ou l'émulateur Android :

bun run mobile:android

Dans Xcode (iOS) :

1. Sélectionnez un émulateur dans le menu déroulant des appareils
2. Appuyez sur le bouton Play ou appuyez sur Cmd + R

In Android Studio :

1. Attendez que Gradle termine de synchroniser
2. Sélectionnez un émulateur dans le menu déroulant des appareils
3. Appuyez sur le bouton Exécuter ou appuyez sur Shift + F10

Étape 8 : Configurer Live Reload

Pour un développement plus rapide, activez la mise à jour en temps réel afin que les modifications apparaissent instantanément sur votre appareil.

1. Trouvez votre adresse IP locale :

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. Create a development Capacitor config. Update capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

3. Démarrer le serveur de développement et copiez la configuration vers native :

bun run dev &
NODE_ENV=development bunx cap copy

4. Rebâtissez dans Xcode/Android Studio

Maintenant, les modifications apportées à votre Nuxt code se refléteront en temps réel sur l'appareil.

Étape 9 : Créez votre première écran mobile

Créons une page d'accueil mobile. Mettre à jour app/app.vue:

<template>
  <NuxtPage />
</template>

Créer app/pages/index.vue:

<template>
  <main
    class="min-h-screen bg-linear-to-b from-green-500 to-green-700 flex flex-col items-center justify-center p-6 text-white"
  >
    <h1 class="text-4xl font-bold mb-4">My Mobile App</h1>
    <p class="text-xl mb-8 text-center opacity-90">
      Built with Nuxt 4 + Capacitor 8
    </p>

    <div v-if="appInfo" class="bg-white/20 rounded-lg p-4 backdrop-blur-sm mb-8">
      <p class="text-sm">
        {{ appInfo.name }} v{{ appInfo.version }}
      </p>
    </div>

    <div class="space-y-4 w-full max-w-sm">
      <button
        class="w-full py-4 px-6 bg-white text-green-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform"
        @click="handleGetStarted"
      >
        Get Started
      </button>
      <button
        class="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform"
        @click="handleShare"
      >
        Share App
      </button>
    </div>
  </main>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';

const appInfo = ref<{ name: string; version: string } | null>(null);

let backButtonListener: { remove: () => void } | null = null;

onMounted(async () => {
  // Get app info
  try {
    appInfo.value = await App.getInfo();
  } catch (e) {
    // Web fallback
    appInfo.value = { name: 'My Mobile App', version: '1.0.0' };
  }

  // Handle Android back button
  backButtonListener = await App.addListener('backButton', ({ canGoBack }) => {
    if (!canGoBack) {
      App.exitApp();
    } else {
      window.history.back();
    }
  });
});

onUnmounted(() => {
  backButtonListener?.remove();
});

function handleGetStarted() {
  // Navigate to onboarding or main app
  console.log('Get started clicked');
}

async function handleShare() {
  // We'll implement this with the Share plugin later
  console.log('Share clicked');
}
</script>

Étape 10 : Ajoutez Tailwind CSS

Pour que la mise en forme fonctionne, ajoutez Tailwind CSS à votre projet :

bun add tailwindcss @tailwindcss/vite

Mettre à jour nuxt.config.ts:

import tailwindcss from '@tailwindcss/vite';

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  ssr: true,
  nitro: {
    preset: 'static',
  },

  css: ['~/assets/css/main.css'],

  vite: {
    plugins: [tailwindcss()],
  },
});

Créer app/assets/css/main.css:

@import 'tailwindcss';

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input,
textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

Étape 11 : Ajoutez le plugin de partage

Créons la fonctionnalité du bouton de partage :

bun add @capacitor/share

Pour utiliser le plugin de partage : app/pages/index.vue Synchro et rebuild :

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';
import { Share } from '@capacitor/share';

// ... existing code ...

async function handleShare() {
  try {
    await Share.share({
      title: 'Check out this app!',
      text: 'Built with Nuxt 4 and Capacitor 8',
      url: 'https://capacitorjs.com',
      dialogTitle: 'Share with friends',
    });
  } catch (e) {
    console.log('Share cancelled or failed:', e);
  }
}
</script>

Étape 12 : Ajoutez le plugin de partage

bun run mobile

Structure du projet

Votre projet devrait ressembler à ceci :

my-mobile-app/
├── android/                  # Android native project
├── ios/                      # iOS native project
├── .output/
│   └── public/              # Static build output
├── app/
│   ├── assets/
│   │   └── css/
│   │       └── main.css
│   ├── pages/
│   │   └── index.vue
│   └── app.vue
├── capacitor.config.ts       # Capacitor configuration
├── nuxt.config.ts            # Nuxt configuration
├── package.json
└── ...

Étapes suivantes

Vous avez maintenant une application mobile Nuxt fonctionnelle. Voici ce que vous devez faire ensuite :

Configuration essentielle

• Icônes de l'application : Remplacez les icônes par défaut dans ios/App/App/Assets.xcassets et android/app/src/main/res
• Écran de démarrage personnalisé : Configurez dans les projets natifs ou utilisez @capacitor/splash-screen config
• Lien profond : Configurez les schémas de URL pour votre application

Ajoutez plus de fonctionnalités

• Caméra : bun add @capacitor/camera
• Localisation : bun add @capacitor/geolocation
• Notifications push : bun add @capacitor/push-notifications ou @capgo/capacitor-firebase-messaging @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-firebase-messaging
• pour Firebase Cloud Messaging sur iOS et Android bun add @capacitor/filesystem

Système de fichiers :

Use Capgo plugins instead of Konsta UI for a native mobile feel:

• @capgo/capacitor-native-navigation — Barre de navigation en verre liquide et barre de navigation native
• @capgo/capacitor-transitions — Transitions de page avec un sentiment de navigation native

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

Pour les zones de sécurité Tailwind, ajoutez @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Voir Utilisation de @capgo/capacitor-navigation-native, Utilisation de @capgo/capacitor-transitions, et le repo tailwind-capacitor pour la configuration spécifique à Nuxt.

Résolution des 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 overflow-x: hidden ou ajuster la balise de viewport seule 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 viewport est appliquée correctement

Dans nuxt.config.ts, définissez le viewport à l'aide de 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 — 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 de .app-shellLe padding de l'espace sûr dupliqué dans les en-têtes, les modales 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 à l'aide d'utilitaires comme pt-safe pb-safe px-safe sur cette seule coquille.

Définir Capacitor iOS contentInset à never premier

Dans capacitor.config.ts, préférez les paramètres d'insertion natifs désactivés et laissez CSS (ou la navigation native) gérer l'espace sûr : contentInsetMode: 'css'Mélanger les paramètres d'insertion automatiques de __CAPGO_KEEP_0__ avec CSS

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trouvez l'élément qui déborde vraiment

Le coupable habituel est un élément utilisant

, Tailwind 100vwpréférez les paramètres d'insertion natifs désactivés et laissez CSS (ou la navigation native) gérer l'espace sûr : w-screen, une largeur fixe en pixels, ou 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-screend'une duplication de la marge de sécurité de l'aire sûre, ou d'un conteneur à largeur fixe — et non de la balise meta de la zone de visualisation elle-même.

Actualisations hors ligne

Configurez Capgo pour envoyer des mises à jour sans résoumission de l'application sur le magasin :

bunx @capgo/cli init

Résolution de problèmes

context : Page/zone : Support / support premium ou section de support du pied de page. Rôle : En-tête de section ou de page. Vu dans : page support-policy.astro. Message clé `support_policy_troubleshooting_title` (Titre de la politique de support de la résolution des problèmes). Exécutez bun install et essayez à nouveau.

iOS : « Aucune identité de signature trouvée » Ouvrez Xcode, allez dans Signing & Capabilités, et sélectionnez votre équipe de développement.

Android : « SDK non trouvé » Créez android/local.properties avec sdk.dir=/path/to/android/sdk

Les modifications ne s'affichent pas sur le dispositif Vérifiez que vous avez exécuté bun run mobile après avoir apporté des modifications. Pour le rechargement en direct, vérifiez que l'adresse IP est correcte et que le serveur de développement est en cours d'exécution.

Le dossier .output/public est vide ou manquant Vérifiez que vous avez configuré nitro: { preset: 'static' } en nuxt.config.ts et exécutez bun run generate.

Ressources

• Capacitor 8 Documentation
• Nuxt 4 Documentation
• Capgo - Mises à jour en temps réel
• @ capgo/ capacitor-navigation-native
• @ capgo/ capacitor-transitions
• @ capgo/ tailwind-capacitor

Prêt à livrer votre application ? Découvrez comment Capgo peut vous aider à livrer des mises à jour plus rapidement — s'inscrire à un compte gratuit aujourd'hui.

Continuez de Build une application mobile Nuxt à partir de zéro avec Capacitor 8

Si vous utilisez Build une application mobile Nuxt à partir de zéro avec Capacitor 8 pour planifier l'automatisation de CI/CD, connectez-l’avec Capgo CI/CD pour le flux de workflow du produit dans Capgo CI/CD, Capgo Builds natifs pour le flux de workflow du produit dans Capgo Builds natifs, Capgo Intégrations pour le flux de workflow du produit dans Capgo Intégrations, Intégration CI/CD pour le détail d'implémentation dans Intégration CI/CD, et GitHub Actions d'intégration pour les détails d'implémentation dans GitHub Actions d'intégration.