Ein Nuxt-Mobil-App von Grund auf mit Capacitor 8 erstellen

Einführung

Möchten Sie eine Nuxt-Mobil-App von Grund auf erstellen? Diese Anleitung führt Sie durch das Erstellen eines brandneuen Nuxt 4-Projekts, das von Anfang an für Mobilgeräte konfiguriert ist, und das dann als native iOS- und Android-Apps verpackt wird mit Capacitor 8.

Am Ende dieses Tutorials haben Sie eine funktionierende Mobil-App, die auf Simulatoren läuft, die Sie weiterentwickeln und schließlich auf dem App Store und Google Play veröffentlichen können.

Dauer: ~30 Minuten

Was Sie bauen werden:

• Einen neuen Nuxt 4-Projekt mit der neuesten Verzeichnisstruktur
• Konfiguration für statische Generierung für mobile Geräte
• Capacitor 8 mit wichtigen Plugins
• Native iOS- und Android-Anwendungen
• Einstellung für Live-Reload-Entwicklung

Sie haben bereits eine Nuxt-Anwendung? Überprüfen Sie Ihre Nuxt App auf mobile umwandeln anstatt.

Voraussetzungen

Stellen Sie sicher, dass Sie diese installiert haben:

• 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 App 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 Ihr 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 Generierung:

bun run generate

Sie sollten ein .output/public Verzeichnis mit Ihren statischen Dateien sehen.

Schritt 4: Installieren Sie Capacitor 8

Installieren Sie die Capacitor-Kernpakete:

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

Installieren Sie wichtige Plugins, die die meisten mobilen Apps benötigen:

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

Was diese Plugins tun:

• @capacitor/app — Ereignisse im App-Lebenszyklus (Vordergrund/Hintergrund, tiefere Links)
• @capacitor/keyboard — Tastaturverhalten steuern
• @capacitor/splash-screen — Kontrolle der nativen Splash-Screen
• @capacitor/status-bar — Stilen Sie die Geräte-Statusleiste
• @capacitor/preferences — Schlüssel-Wert-Speicher (wie localStorage, aber native)

Schritt 5: Initialisieren Sie Capacitor

Initialisieren Sie Capacitor mit Ihren Projekt-Daten:

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

Ersetzen:

• "My Mobile App" mit dem Namen Ihres Anwendungs-Displays
• com.example.mymobileapp mit Ihrer Anwendungs-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

Generieren 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

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

bun run mobile

In iOS Simulator öffnen:

bun run mobile:ios

Oder Android-Emulator:

bun run mobile:android

In Xcode (iOS):

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

In Android Studio:

1. Warten Sie, bis Gradle fertig ist, die Synchronisierung durchzuführen
2. Wählen Sie einen Emulator aus dem Geräte-Auswahldropdown
3. Klicken Sie auf die Ausführen-Schaltfläche oder drücken Sie Shift + F10

Schritt 8: Einrichten von Live Reload

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. Erstellen Sie eine Entwicklungskonfiguration Capacitor. Aktualisieren Sie 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

Jetzt werden Änderungen an Ihrem Nuxt code auf dem Gerät sofort neu geladen.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirmoberfläche

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

<template>
  <NuxtPage />
</template>

Erstellen Sie 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: Hinzufügen von Tailwind CSS

Für die Gestaltung zu aktivieren, 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 das Teilen-Plugin hinzu

Lassen Sie uns die Funktion des Teilen-Buttons 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 aufbauen:

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

Sie haben jetzt eine funktionierende Nuxt-Mobilanwendung. Hier sind die nächsten Schritte:

Grundlegende Einrichtung

• App Icons: Ersetzen Sie die Standardicons in ios/App/App/Assets.xcassets und android/app/src/main/res
• Splash Screen: Anpassen Sie in native Projekten oder verwenden Sie @capacitor/splash-screen config
• Deep Links: Konfigurieren Sie die URL-Schemas für Ihre App

Hinzufügen Sie weitere Funktionen

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

Natives UI und Übergänge

Verwenden Sie Capgo-Plugins anstelle von Konsta UI für einen nativen mobilen Look:

• @capgo/capacitor-native-navigation — Liquid Glass-Tasteleiste und nativer Navbar
• @capgo/capacitor-transitions — natürliche-sehende Seitenübergänge

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

Für Tailwind-Sicherheitsbereiche, fügen Sie @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Sehen Sie Mit @capgo/capacitor-native-Navigation, Mit @capgo/capacitor-Übergängeund die tailwind-capacitor-Repo für die Nuxt-spezifische Einrichtung.

iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontale Überschuss)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr oder passen Sie den Viewport-Tag alleine normalerweise nicht aus. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird

In

In nuxt.config.tsSet die Ansicht durch app.head:

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

Behandeln Sie die iOS-Sicherheitszone von einem einzigen Root-Wrapper aus

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort die Sicherheitszone-Padding an — nicht in mehreren verschachtelten Komponenten:

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

Verwenden Sie alle Seiteninhalte innerhalb von .app-shellDoppelte Sicherheitszone-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitor, können Sie denselben Padding mit Hilfsmitteln wie pt-safe pb-safe px-safe auf diesem einzelnen Shell ausdrücken.

Setzen Sie Capacitor iOS contentInset auf never erst

In bevorzugen Sie native Eingabefelder, die deaktiviert sind, und lassen Sie CSS (oder Native Navigation’s) capacitor.config.tseinen sicheren Bereich besitzen: contentInsetMode: 'css'Die Mischung von __CAPGO_KEEP_0__’s automatischer Inhaltseinstellung mit 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-*) Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das

, Tailwind 100vw, eine fixe Pixelbreite oder eine große w-screenIn Safari Web Inspector, führen Sie aus: min-width.

Mit Tailwind ersetzen Sie

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

durch w-screen Find the real overflowing element w-full When möglich. Viele horizontale Überschreitungsausgaben kommen von 100vw / w-screen, dupliziertem sicheren Bereichsabstand oder einem festerbreiten Container — nicht von der Viewport-Meta-Tags selbst.

Über-ein-Air-Updates

Einstellungen Capgo um Updates ohne App-Store-Neuabrechnung zu pushen:

bunx @capgo/cli init

Problembehandlung

Build fehlschlägt mit „Cannot find module“ Ausführen bun install und versuche es erneut.

iOS: „Kein Signierungsidentität gefunden“ Öffne Xcode, gehe zu Signing & Capabilities und wähle dein Entwicklerteam.

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

Änderungen erscheinen nicht auf Gerät Stellen Sie sicher, dass Sie nach der Anpassung bun run mobile 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' } in 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

Bereit, Ihre App zu verschicken? Lernen Sie, wie Capgo Ihnen dabei hilft, Updates schneller zu liefern — sich für ein kostenloses Konto anmelden heute.

Weitermachen von Build a Nuxt Mobile App von Grund auf mit Capacitor 8

Wenn Sie " Build a Nuxt Mobile App von Grund auf mit Capacitor 8 zum Planen der CI/CD-Automatisierung verwenden, verbinden Sie es 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 Actions-Integration für die Implementierungsdetails in GitHub Actions-Integration