Ein Nuxt-Mobilanwendungsprojekt von Grund auf mit Capacitor 8 erstellen

Einführung

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

Von diesem Tutorial aus werden Sie eine funktionierende mobile App haben, 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
Konfiguration für statische Generierung für mobile Geräte
Capacitor 8 mit wichtigen Plugins
NATIVE iOS- und Android-Apps
Entwicklungsumgebung mit Live-Reload

Bereits ein Nuxt-App besitzen? Convertieren Sie Ihre Nuxt-App in eine mobile App Voraussetzungen

Prerequisites

Sie benötigen Nuxt 4 und Capacitor

Node.js 18+ (prü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

Erstellen Sie zunächst ein frisches Nuxt 4-Projekt:

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

Dieses Aufbau 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: Hinzufügen von mobilen Skripten

Aktualisieren Sie package.json Die statische Generierung testen:

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

Schritt 4: Installieren Sie __CAPGO_KEEP_0__ 8 .output/public Installieren Sie die __CAPGO_KEEP_0__-Kernpakete:

Installieren Sie die Capacitor-Kernpakete:

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

Install wichtige Plugins, 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 — Lebenszyklusereignisse der App (Vordergrund/Hintergrund, tiefere Links)
@capacitor/keyboard — Tastaturverhalten steuern
@capacitor/Splashbildschirm — Kontrolle der nativen Splash-Screen
@capacitor/status-bar — Gestaltung des Geräte-Status-Bars
@capacitor/preferences — Schlüssel-Wert-Speicherung (wie localStorage, aber nativ)

Schritt 5: Capacitor initialisieren

Initialisiere Capacitor mit deinen Projekt-Daten:

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

Ersatz:

"My Mobile App" mit deinem Anwendungs-Bezeichner
com.example.mymobileapp mit deiner Anwendungs-ID (umgekehrte Domänennotation)

Dies erstellt capacitor.config.tsUpdate 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

Installiere die Plattform-Pakete:

bun add @capacitor/ios @capacitor/android

Erstelle die native Projekte:

bunx cap add ios
bunx cap add android

Dies erstellt ios und android Verzeichnisse mit den native Projekten.

Schritt 7: Erstellen und Ausführen

Deine Projektdateien erstellen und synchronisieren mit nativen Plattformen:

bun run mobile

Öffnen Sie in iOS Simulator:

bun run mobile:ios

Oder Android Emulator:

bun run mobile:android

In Xcode (iOS):

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

In Android Studio:

Warten auf Gradle, bis es synchronisiert ist
Wählen Sie einen Emulator aus dem Geräte-Auswahldropdown
Klicken Sie auf die Run-Taste 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.

Finden Sie Ihre lokale IP-Adresse:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

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;

Starte den Dev-Server und kopiere Konfiguration nach native:

bun run dev &
NODE_ENV=development bunx cap copy

Rebuild in Xcode/Android Studio

Jetzt werden Änderungen an Ihrem Nuxt code auf dem Gerät hot-reload.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirm

Erstellen wir eine mobile-freundliche Startseite. 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

Fügen Sie Tailwind CSS Ihrem Projekt hinzu, damit die Styling funktioniert:

bun add tailwindcss @tailwindcss/vite

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

Implementieren wir nun die Funktion für den Teilen-Button:

bun add @capacitor/share

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

Überprüfen und neu erstellen:

bun run mobile

Projektstruktur

Ihr Projekt sollte nun 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 nun eine funktionierende Nuxt-Mobilanwendung. Hier sind die nächsten Schritte:

Wichtige Einstellungen

App Icons: Ersatz Icons ersetzen in ios/App/App/Assets.xcassets und android/app/src/main/res
Splash Bildschirm: Anpassen in native Projekten oder verwenden @capacitor/splash-screen config
Tiefen Links: URL Schemata für Ihre App konfigurieren

Zusätzliche Funktionen hinzufügen

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

Eigene Benutzeroberfläche und Übergänge

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

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

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

Für Tailwind-Safe-Areas fügen Sie hinzu: @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

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

Fixen von iOS-Anordnungsproblemen (Viewport, sichere Fläche und horizontale Überschreitung)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder das Anpassen der Viewport-Tags allein hilft normalerweise nicht. Arbeiten Sie durch diese Kontrollen in der Reihenfolge.

Stellen Sie sicher, dass die Viewport-Metatag korrekt angewendet wird.

In nuxt.config.ts, setzen Sie das Viewport durch app.head:

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

iOS-Sicherheitsbereich aus einer einzigen Root-Wrapper verwalten

Erstellen Sie eine einzelne App-Shell und fügen Sie dort den Sicherheitsbereich ein — 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);
}

Alle Seiteninhalte innerhalb von .app-shellDoppelte Sicherheitsbereichspaddings in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitorkönnen Sie denselben Puffer mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzigen Schale ausdrücken.

Setzen Sie Capacitor iOS `contentInset` auf `never` erst

In capacitor.config.ts, bevorzugt native Inset deaktivieren und lassen Sie CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Fläche besitzen:

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

Mischen Sie Capacitor’s automatische Inhaltseinstellung mit CSS env(safe-area-inset-*) padding ist eine häufige Ursache für doppelte Abstände.

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, führen Sie aus:

[...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-screenoder doppelte sichere Bereiche oder ein fester Breitencontainer — nicht aus der Meta-Tag des Viewports selbst.

Over-the-Air-Updates

Einrichten Capgo um Updates ohne Wiederabgabe im App-Store zu pushen:

bunx @capgo/cli init

Troubleshooting

Build fehlt mit „Cannot find module“ Laufen bun install und probiere 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 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' } in nuxt.config.ts und ausführen bun run generate.

Ressourcen

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

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

Wenn Sie bereits Build a Nuxt Mobile App von Grund auf mit Capacitor 8 zur Planung der CI/CD-Automatisierung, mit ihr verbinden Capgo CI/CD für den Produktworkflow in Capgo CI/CD, Capgo nativee 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.

Mit Capacitor 8 einen Nuxt Mobile App von Grund auf aufbauen