Ihre Nuxt App auf iOS & Android umwandeln mit Capacitor 8

Introduction

Haben Sie bereits eine Nuxt-Webanwendung? In dieser Anleitung lernen Sie, wie Sie sie in native iOS- und Android-Mobilanwendungen umwandeln können. Capacitor 8 — die neueste Version mit verbesserten Leistungen und neuen Funktionen.

Capacitor umhüllt Ihre Webanwendung in einen nativen Container, der Ihnen Zugriff auf Geräte-APIs wie Kamera, Dateisystem und Benachrichtigungen bietet, während Ihre bestehende Vue-Codebasis erhalten bleibt. Im Gegensatz zu Flutter oder React Native müssen Sie nichts umschreiben — Ihre Nuxt code läuft unverändert.

Was Sie lernen werden:

• Konfigurieren Sie Ihre bestehende Nuxt-Anwendung für statische Generierung
• Fügen Sie Capacitor 8 mit wesentlichen nativen Plugins hinzu
• Erstellen und testen Sie auf iOS- und Android-Emulatoren
• Aktivieren Sie Live-Reload für eine schnellere Entwicklung
• Beheben Sie häufige iOS-Anzeigeeinrichtungsprobleme (viewport, sichere Fläche, horizontale Überlauf)
• Fügen Sie native anfühlsame UI mit Capgo Native Navigation und Transitions hinzu

Sind Sie auf der Suche nach einer neuen Projektidee von vorne? Entdecken Sie unsere Anleitung zu.

Vorteile der Verwendung von Nuxt und Capacitor

• Code Reusability: Teilen Sie Ihre Vue-Komponenten und Logik zwischen Web- und Mobilanwendungen.
• Leistung: Nuxt’s statische Generierung erstellt optimierte Pakete, die perfekt für Mobilgeräte geeignet sind.
• Nativfunktionen: Zugreifen Sie auf Gerätefeatures wie Kamera, Geolocation und Dateisystem über Capacitor-Plugins.
• Einfache Entwicklung: Verwenden Sie bekannte Vue/Nuxt-Muster ohne das Erlernen von nativer Entwicklung.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Node.js 18+ installiert
• Ein bestehendes Nuxt 4 Anwendungsprojekt
• Xcode (für iOS-Entwicklung, nur macOS)
• Android Studio (für Android-Entwicklung)

Konfigurieren Sie Ihre Nuxt-Anwendung für mobile Geräte

Der erste Schritt besteht darin, Ihre Nuxt-Anwendung für die statische Generierung zu konfigurieren. Capacitor benötigt statische HTML/JS/CSS-Dateien, um sie in die native App zu bündeln.

Stellen Sie sicher, dass Ihr Projekt package.json den generierenden Skript enthält:

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

Wichtig: Wenn Sie serverseitige Funktionen (z.B. API Routen, Server-Middleware usw.) verwenden, müssen Sie diese auf clientseitige Alternativen oder externe APIs umstellen.

Testen Sie die statische Generierung, indem Sie:

bun run generate

Sie sollten ein .output/public Ordner mit Ihren statischen Dateien sehen. Dies ist, was Capacitor in Ihre native App einbündeln wird.

Capacitor 8 zu Ihrem Projekt hinzufügen

Um Ihre Nuxt-App in einen nativen mobilen Container zu packen, folgen Sie diesen Schritten:

1. Installieren Sie Capacitor Core und CLI:

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

2. Installieren Sie gängige Capacitor-Plugins, die Sie benötigen:

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

Diese Plugins liefern wichtige Funktionen:

• @capacitor/app: Lebenszyklusereignisse der Anwendung verwalten (Vordergrund/Hintergrund, tiefere Links)
• @capacitor/keyboard: Tastaturverhalten auf Mobilgeräten steuern
• @capacitor/splash-screen: Die native Splash-Screen verwalten
• @capacitor/status-bar: Die Geräte-Statusleiste anpassen
• @capacitor/preferences: Schlüssel-Wert-Speicherung (wie localStorage, aber native)

3. Initialize Capacitor mit Ihren Projekt-Daten:

bunx cap init my-app com.example.myapp --web-dir .output/public

Ersetzen my-app mit Ihrem App-Namen und com.example.myapp mit Ihrer App-ID (umgekehrte Domänennotation).

4. Erstellen oder aktualisieren Sie das capacitor.config.ts Datei mit der richtigen Konfiguration:

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;

5. Installieren Sie native Plattformen:

bun add @capacitor/ios @capacitor/android

6. Fügen Sie die native Plattform-Ordner hinzu:

bunx cap add ios
bunx cap add android

Capacitor wird ios und android Ordner am Root Ihres Projekts erstellen, die die native Projekte enthalten.

Um das Android-Projekt zu bauen, benötigen Sie Android Studio. Für iOS benötigen Sie einen Mac mit Xcode.

7. Ihr Projekt bauen und synchronisieren:

bun run mobile

Dies läuft Ihren benutzerdefinierten Skript, das die statische Nuxt-Build erstellt und die Dateien mit den nativen Plattformen synchronisiert.

Erstellung und Bereitstellung von Native-Apps

Um Ihre native mobile App zu erstellen und zu verteilen, folgen Sie bitte diesen Schritten:

Um iOS-Apps zu entwickeln, müssen Sie Xcode installiert haben, und für Android-Apps müssen Sie Android Studio installiert haben. Darüber hinaus müssen Sie, wenn Sie Ihre App im App Store verteilen möchten, sich für iOS im Apple Developer Programm und für Android im Google Play Console anmelden.

1. Die native Projekte öffnen:

Für iOS:

bun run mobile:ios

Für Android:

bun run mobile:android

Oder direkt mit Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Die App erstellen und ausführen:

• In Android Studio wartet man auf das Projekt, und klickt dann auf den „Ausführen“-Button, um die App auf einem verbundenen Gerät oder Emulator zu deployen.

• In Xcode stellt man sein Signierkonto ein, um die App auf einem echten Gerät zu deployen. Wenn man das noch nicht gemacht hat, wird Xcode durch den Prozess führen (beachten Sie, dass man sich bei dem Apple Developer Programm anmelden muss). Sobald man eingestellt ist, klickt man auf den „Play“-Button, um die App auf dem verbundenen Gerät auszuführen.

Glückwunsch! Sie haben erfolgreich Ihre Nuxt-Web-App auf einem mobilen Gerät deployt.

Aber halt, es gibt auch eine schnellere Möglichkeit, dies während der Entwicklung zu tun…

Capacitor Live Reload

Während der Entwicklung kann man von Live-Reloaden profitieren, um Änderungen sofort auf dem mobilen Gerät sehen zu können. Um diese Funktion zu aktivieren, folgt man diesen Schritten:

1. Finden Sie Ihre lokale IP-Adresse:

• Auf macOS ausführen Sie folgenden Befehl in der Terminal-Anwendung:

  ipconfig getifaddr en0

• Auf Windows ausführen:

  ipconfig

  Suchen Sie nach der IPv4-Adresse in der Ausgabe.

2. Aktualisieren Sie Ihren capacitor.config.ts um auf Ihren Entwicklungsserver zu zeigen:

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;

Ersetzen Sie YOUR_IP_ADDRESS mit Ihrer lokalen IP-Adresse (z.B. 192.168.1.100).

3. Anwenden Sie die Änderungen an Ihrem native Projekt:

bunx cap copy

Die copy -Anweisung kopiert das Web-Ordner und die Konfigurationsänderungen in das native Projekt ohne Aktualisierung des gesamten Projekts.

4. Starten Sie Ihren Nuxt-Dev-Server und rebuilden Sie in Xcode/Android Studio:

bun run dev

Jetzt werden die Änderungen an Ihrem Nuxt-App automatisch neu geladen, sobald Sie Änderungen vornehmen.

Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an native Dateien vornehmen, müssen Sie das native Projekt neu erstellen, da nur Web-code-Änderungen live neu geladen werden.

Mit Capacitor-Plugins

Capacitor-Plugins ermöglichen Ihnen, Zugriff auf native Gerätefeatures von Ihrer Nuxt-App zu erhalten. Lassen Sie uns sehen, wie Sie das Teilen-Plugin als Beispiel verwenden können.

1. Das Teilen-Plugin installieren:

bun add @capacitor/share

2. Eine Seite erstellen oder aktualisieren, um das Teilen-Plugin zu verwenden. In Nuxt 4 gehen Seiten in 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>

3. Die Änderungen mit dem native Projekt synchronisieren:

bun run mobile

Oder einfach synchronisieren, ohne neu zu erstellen:

bunx cap sync

4. Das Projekt neu erstellen und auf Ihrem Gerät ausführen.

Now, wenn Sie auf den Button „Jetzt teilen!“ klicken, erscheint das native Teilen-Dialogfeld.

Als Nächstes können Sie die App auf iOS und Android mit Capgo-Navigation und -Übergängen noch nativer anfühlen lassen und gängige iOS-Anordnungsprobleme lösen, die zu horizontaler Überschreitung oder gekürzten sicheren Bereichen führen.

Native anfühlen – UI mit Capgo-Native-Navigation und -Übergängen

Jahre lang habe ich mit Ionic gearbeite, um cross-plattformische Anwendungen zu erstellen, aber die Integration mit Nuxt ist hackig und selten wertvoll, wenn Sie bereits Tailwind CSS.

For a native mobile feel in a Nuxt + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

• Für einen nativen mobilen Look in einer Nuxt + capgo-Anwendung verwenden Sie stattdessen capacitor-Plugins anstelle von web-only UI-Kits wie Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
• @capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

Install beide:

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

Konfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit Webinhalte die native Balken respektieren:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendern Sie eine Liquid Glass-Taste (iOS verwendet die Systemeigene Rendering; Android verwendet einen verschmierten WebView-Hintergrund):

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

Fügen Sie native Seitenübergänge in Ihrem App-Shell hinzu:

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

Umfasst die gerouteten Seiten in cap-router-outlet, cap-page, und cap-content, und rufen Sie setDirection('forward') oder setDirection('back') vor der Navigation auf. Duplizieren Sie Web-Über- oder Fußzeilen nicht, wenn die native Navigation diese Oberflächen besitzt.

Sehen Sie sich die vollständigen Anleitungen an: Mit @capgo/capacitor-native-navigation und Mit @capgo/capacitor-Übergängen verwenden.

Sichere Bereiche mit Tailwind

Für sichere Bereiche auf Geräten in Tailwind CSS verwenden @capgo/tailwind-capacitor (als tailwind-capacitor auf npm). Es bietet safe-areas Nützliche Funktionen und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

In app/assets/css/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Für Nuxt 4 mit Tailwind CSS 4, behalten Sie diese Import-Anweisung im CSS-File bei, das von nuxt.config.ts.

Verwenden Sie Nützlichkeiten wie pt-safe, pb-safe, und px-safe anstatt, sie überall zu verteilen env(safe-area-inset-*) von Hand. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Nuxt-Konfiguration fehlt, Öffnen Sie einen PR auf GitHub.

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

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder passen Sie allein den Viewport-Tag an, reicht normalerweise nicht aus. 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',
        },
      ],
    },
  },
});

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

Erstellen Sie ein einzelnes App-Shell und wenden Sie dort Safe-Area-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 .app-shellDoppelte Safe-Area-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aus.

Mit @capgo/tailwind-capacitor, können Sie denselben Rand mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Shell.

Setzen Sie Capacitor iOS contentInset auf never erstes

In capacitor.config.ts, bevorzugen Sie native inset deaktiviert 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: 'out',
  ios: {
    contentInset: 'never',
  },
};

Die Mischung von Capacitor’s automatischem Inhaltseinschub mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelten Abstand.

Finden Sie das echte überlaufende Element

Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine fixe 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 sicherem Bereichsabstand oder einem festen Breitencontainer — nicht von der Viewport-Meta-Tags selbst.

Schlussfolgerung

Sie haben erfolgreich Ihre bestehende Nuxt-Web-Anwendung in native iOS- und Android-Apps umgewandelt, indem Sie Capacitor 8 verwendet haben. Ihre Vue-Codebasis läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräte-APIs.

Was Sie erreicht haben:

• Konfiguriert Nuxt für statische Generierung
• Hinzugefügt Capacitor 8 mit wesentlichen Plugins
• Erstellt und bereitgestellt auf iOS- und Android-Simulatoren
• Aktiviert Live-Reload für Entwicklung
• Löste häufige iOS-Ansichtsprobleme (viewport, sichere Bereich, Überlauf)
• Fügte native anfühlfende UI mit Capgo Native Navigation und Transitions hinzu

Nächste Schritte:

• Einrichten Capgo für über Draht-Updates ohne App-Store-Wiederabgabe
• Fügen Sie mehr native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzu
• Konfigurieren Sie App-Icons und Splash-Screens für die Produktion
• Ihre App auf App Store und Google Play vorbereiten

Ein neues Projekt starten? Überprüfen Sie Ein Nuxt Mobile App von Grund auf bauen für eine geführte Anleitung.

Ressourcen

• Nuxt-Dokumentation
• Capacitor 8 Dokumentation
• @capgo/capacitor-native-Navigation — Liquid Glass-Tasteleiste und native Chrome
• @capgo/capacitor-Übergänge — native-fühlende Seitenübergänge
• @capgo/tailwind-capacitor — Sicherheitsbereiche für Capacitor mit Tailwind
• Capgo - Live Updates für Capacitor Apps

Erhalten Sie Informationen darüber, wie Capgo Ihnen helfen kann, bessere Apps schneller zu entwickeln, sich für ein kostenloses Konto anmelden heute.

Fortsetzen Sie mit Konvertieren Sie Ihre Nuxt App in iOS & Android mit Capacitor 8

Wenn Sie native Plugin-Arbeiten planen, verbinden Sie es mit Capacitor Plugin-Verzeichnis für den Produktworkflow in __CAPGO_KEEP_0__ Plugin-Verzeichnis, Capgo Plugins von __CAPGO_KEEP_1__ Convert Your Nuxt App to iOS & Android with Capgo 8 Capacitor Plugins by Capgo für die Implementierungsdetails in Capacitor Plugins durch Capgo, Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, Ionic Enterprise Plugin Alternativen für den Produktworkflow in Ionic Enterprise Plugin Alternativen, und Capgo Native Builds für den Produktworkflow in Capgo Native Builds.