Ein Nuxt-Mobilanwendung von Grund auf bauen mit Capacitor 8

Einleitung

Wollen Sie eine mobile App mit Nuxt von Grund auf aufbauen? Diese Anleitung führt Sie durch die Erstellung eines brandneuen Nuxt 4-Projekts, das von Anfang an für mobile Geräte konfiguriert ist, und das dann als native iOS- und Android-Apps verpackt. Capacitor 8.

Mit dieser Anleitung haben Sie am Ende eine funktionierende mobile App, die auf Simulatoren läuft, die Sie weiterentwickeln und schließlich auf die App Store und Google Play veröffentlichen können.

Zeitaufwand: ~30 Minuten

Was Sie bauen werden:

• Ein neues Nuxt 4-Projekt mit der neuesten Verzeichnisstruktur
• Statistische Generierungskonfiguration für mobile Geräte
• Capacitor 8 with essential plugins
• Native iOS- und Android-Apps
• Live-Reload-Entwicklungsumgebung

Bereits ein Nuxt-Projekt vorhanden? Ihre Nuxt App auf Mobilgeräte umstellen anstatt.

Voraussetzungen

Stellen Sie sicher, dass diese installiert sind:

• Node.js 18+ (überprüfen Sie mit node --version)
• Bun Paketmanager (curl -fsSL https://bun.sh/install | bash)
• Xcode (nur für macOS, für iOS-Entwicklung)
• Android Studio (für Android-Entwicklung)

Schritt 1: Erstellen Sie ein neues Nuxt 4-Projekt

Beginnen Sie mit der Erstellung eines frischen Nuxt 4-Projekts:

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

Nuxt 4-Verzeichnisstruktur

Nuxt 4 verwendet eine neue Verzeichnisstruktur mit app code im app/ Verzeichnis:

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

Diese Struktur bietet eine bessere Trennung zwischen Anwendung und Server code.

Schritt 2: Konfigurieren Sie Nuxt für statische Generierung

Capacitor erfordert statische HTML/JS/CSS-Dateien. Konfigurieren Sie Nuxt für statische Generierung in nuxt.config.ts:

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

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

Schritt 3: Fügen Sie mobile Skripte hinzu

Aktualisieren Sie Ihre package.json mit mobilen Entwicklungs-Skripten:

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

Testen Sie die statische Erzeugung:

bun run generate

Sie sollten ein Verzeichnis mit Ihren statischen Dateien sehen. .output/public Schritt 4: Installieren Sie __CAPGO_KEEP_0__ 8

Installieren Sie die Capacitor-Kernpakete:

Install the Capacitor core packages:

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

Was diese Plugins tun:

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

@__CAPGO_KEEP_0__/app

• @capacitor/app @__CAPGO_KEEP_0__/keyboard
• @capacitor/keyboard @__CAPGO_KEEP_0__/splash-screen
• @capacitor/splash-screen — Kontrolle der native Splash-Screen
• @capacitor/status-bar — Die Geräte-Status-Leiste stylen
• @capacitor/preferences — Schlüssel-Wert-Speicherung (wie localStorage, aber native)

Schritt 5: Capacitor initialisieren

Capacitor mit Ihren Projekt-Daten initialisieren:

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

Ersetzen Sie:

• "My Mobile App" mit dem Namen Ihres Anwendungs-Displays
• com.example.mymobileapp mit Ihrer App-ID (umgekehrte Domänennotation)

Dies erstellt capacitor.config.ts. Aktualisieren Sie es mit Plugin-Konfiguration:

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;

Schritt 6: Hinzufügen von Native Plattformen

Installieren Sie die Plattform-Pakete:

bun add @capacitor/ios @capacitor/android

Erstellen Sie die native Projekte:

bunx cap add ios
bunx cap add android

Dies erstellt ios und android Verzeichnisse, die die native Projekte enthalten.

Schritt 7: Erstellen und Ausführen

Bauen Sie Ihr Projekt und synchronisieren Sie es mit den native Plattformen:

bun run mobile

Öffnen Sie in iOS-Simulator:

bun run mobile:ios

Oder Android-Emulator:

bun run mobile:android

In Xcode (iOS):

1. Wählen Sie einen Simulator aus dem Geräte-Auswahlfeld
2. Klicken Sie auf den Play-Button oder drücken Sie Cmd + R

In Android Studio:

1. Warten Sie, bis Gradle fertig ist
2. Wählen Sie ein Emulator aus dem Geräte-Auswahlfeld
3. Klicken Sie auf den Run-Button oder drücken Sie Shift + F10

Schritt 8: Live Reload einrichten

Für eine schnellere Entwicklung aktivieren Sie Live Reload, damit Änderungen sofort auf Ihrem Gerät erscheinen.

1. Finden Sie Ihre lokale IP-Adresse:

# 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. Starten Sie den Entwicklungs-Server und kopieren Sie die Konfiguration in die native Umgebung:

bun run dev &
NODE_ENV=development bunx cap copy

4. Rebuild in Xcode/Android Studio

Now edits to your Nuxt code will hot-reload on the device.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirm

Lassen Sie uns eine mobile-freundliche Startseite erstellen. Aktualisieren app/app.vue:

<template>
  <NuxtPage />
</template>

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

Schritt 10: Fügen Sie Tailwind CSS hinzu

Damit die Stylisierung funktioniert, fügen Sie Tailwind CSS Ihrem Projekt hinzu:

bun add tailwindcss @tailwindcss/vite

Aktualisieren 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()],
  },
});

Erstellen 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;
}

Schritt 11: Fügen Sie den Teilen-Plugin hinzu

Lassen Sie uns die Funktion zum Teilen implementieren:

bun add @capacitor/share

Aktualisieren app/pages/index.vue um das Teilen-Plugin zu verwenden:

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

Synchronisieren und neu erstellen:

bun run mobile

Projektstruktur

Ihr Projekt sollte jetzt wie folgt aussehen:

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

Nächste Schritte

Zum Ziel

Ihr Nuxt-Mobilanwendung funktioniert jetzt. Hier sind die nächsten Schritte:

• Wichtige Einstellungen App-Icons: ios/App/App/Assets.xcassets Ersatz der Standardicons in android/app/src/main/res
• und Willkommensbildschirm: @capacitor/splash-screen Anpassen in native Projekten oder verwenden
• Konfigurationen von Deep Links: Konfigurieren Sie die URL-Schemas für Ihre App

Hinzufügen Sie weitere Funktionen

• Kamera: bun add @capacitor/camera
• Standort: bun add @capacitor/geolocation
• Push-Benachrichtigungen: bun add @capacitor/push-notifications oder @capgo/capacitor-firebase-messaging @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-firebase-messaging
• für Firebase Cloud Messaging auf iOS und Android bun add @capacitor/filesystem

Dateisystem:

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

• Verwenden Sie stattdessen capgo-Plugins, um ein nativ anmutendes Benutzerinterface zu erhalten: @capgo/capacitor-native-navigation — Glasflüssigkeit-Taste für die Tab-Leiste und native Navbar
• @capgo/capacitor-Übergänge — Übergänge mit natürlicher Seite

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

Fügen Sie für sichere Bereiche von Tailwind hinzu @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Siehe Verwendung von @capgo/capacitor-native-Navigation, Verwendung von @capgo/capacitor-Übergänge, und das tailwind-capacitor-Repo für die Nuxt-spezifische Einrichtung.

Lösen von iOS-Layout-Problemen (Viewport, sichere Bereiche und horizontale Überlauf)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, hilft das Hinzufügen von mehr overflow-x: hidden oder das Anpassen der Viewport-Tags alleine normalerweise nicht.

Durchführen Sie diese Kontrollen in der Reihenfolge.

Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird nuxt.config.tsIn app.head:

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

, setzen Sie den Viewport über

Behandeln Sie das iOS-Safe-Area von einem einzigen Root-Wrapper aus

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);
}

Erstellen Sie ein einzelnes App-Shell und wenden Sie dort Safe-Area-Padding an — nicht in mehreren verschachtelten Komponenten: .app-shellUmfasst alle Seite-Inhalte innerhalb von

Doppelte Safe-Area-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die UI oft gekürzt oder zu groß aussehen. @capgo/tailwind-capacitor@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ pt-safe pb-safe px-safe auf dieser einzelnen Shell.

Setzen Sie Capacitor iOS contentInset bis zu never erst

In capacitor.config.ts, bevorzugt native eingefrorene und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') den sicheren Bereich besitzen:

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

Mischen Sie Capacitor's automatische Inhaltsabstand mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelten Abstand.

Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine feste Pixelbreite oder eine große min-width.

In Safari Web Inspector, ausführen:

[...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,
  }));

Mit Tailwind ersetzen Sie w-screen mit w-full wenn möglich. Viele horizontale Überlaufprobleme kommen von 100vw / w-screen, dupliziertem sicheren Bereichsabstand oder einer festerbreiten Container — nicht von der Viewport-Meta-Tags selbst.

Over-the-Air-Updates

Einstellungen Capgo Troubleshooting

bunx @capgo/cli init

Builds scheitern mit „Cannot find module“

__CAPGO_KEEP_0__ Starten bun install und versuchen Sie es erneut.

iOS: "Kein Signierungsidentität gefunden" Öffnen Sie Xcode, gehen Sie zu Signierung und Fähigkeiten und wählen Sie Ihr Entwicklungsteam.

Android: "SDK-Ort nicht gefunden" Erstellen android/local.properties mit sdk.dir=/path/to/android/sdk

Änderungen erscheinen nicht auf dem Gerät Stellen Sie sicher, dass Sie bun run mobile nachdem Sie Änderungen vorgenommen haben. Für Live-Reload überprüfen Sie, ob die IP-Adresse korrekt ist und der Entwicklungs-Server läuft.

.output/public ist leer oder fehlt Stellen Sie sicher, dass Sie nitro: { preset: 'static' } Inbetriebnahme nuxt.config.ts und ausführen bun run generate.

Ressourcen

• Capacitor 8 Dokumentation
• Nuxt 4 Dokumentation
• Capgo - Live-Updates
• @capgo/capacitor-native-Navigation
• @capgo/capacitor-Übergänge
• @capgo/tailwind-capacitor

Sind Sie bereit, Ihre App zu verschicken? Erfahren Sie, wie Capgo Ihnen dabei helfen kann, Updates schneller zu liefern — Kostenlos anmelden heute.

Fortsetzung von Build eine Nuxt-Mobil-App von Grund auf mit Capacitor 8

Wenn Sie Build eine Nuxt-Mobil-App von Grund auf mit Capacitor 8 um die CI/CD-Automatisierung zu planen, verbinden Sie sie mit Capgo CI/CD für den Produktworkflow in Capgo CI/CD, Capgo Native Builds für den Produktworkflow in Capgo Native Builds, Capgo Integrations für den Produktworkflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub Aktionen-Integration zur Implementierungsdetail in GitHub Aktionen-Integration.