Convert Your Nuxt App to iOS & Android with Capacitor 8

Einführung

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

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.

Was Sie lernen werden:

• Configure your existing Nuxt app for static generation
• Fügen Sie Capacitor 8 mit wichtigen nativen Plugins hinzu
• Bauen und testen auf iOS- und Android-Emulatoren
• Aktiviere Live-Neustart für schnellere Entwicklung
• Kommune iOS-Anordnungsprobleme beheben (Ansicht, sichere Fläche, horizontale Überlauf)
• Mit natürlicher Anmutung UI hinzufügen mit Capgo Native Navigation und Übergänge

Planen Sie ein neues Projekt von Grund auf? Überprüfen Sie unsere Anleitung zu Ein Nuxt-Mobil-App von Grund auf erstellen.

Vorteile der Verwendung von Nuxt und Capacitor

• Code Wiederverwendbarkeit: Teilen Sie Ihre Vue-Komponenten und Logik zwischen Web- und Mobilanwendungen.
• LeistungNuxt generiert statische Versionen, die optimale Bundle für mobile Geräte erzeugen.
• Nativfunktionen: Zugriff auf Gerätefunktionen wie Kamera, Geolocation und Dateisystem über Capacitor-Plugins.
• Einfache Entwicklung: Verwenden Sie bekannte Vue/Nuxt-Muster ohne das Erlernen der nativen Entwicklung.

Voraussetzungen

Before you begin, make sure you have:

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

Configuring Your Nuxt App for Mobile

The first step is to configure your Nuxt app for static generation. Capacitor needs static HTML/JS/CSS files to bundle into the native app.

Stellen Sie sicher, dass Ihr package.json hat den generate-Skript:

{
  "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 einpacken wird.

Hinzufügen von Capacitor 8 zu Ihrem Projekt

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

1. Install Capacitor Kern und CLI:

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

2. Install gängige Capacitor-Plugins, die du wahrscheinlich benötigst:

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

Diese Plugins liefern wichtige Funktionen:

• @capacitor/app: Verwalte das Lebenszyklus von App (Vordergrund/Hintergrund, tiefere Links)
• @capacitor/TastaturKontrolle der Tastaturverhalten auf Mobilgeräten
• @capacitor/Splashbildschirm: Verwalte die native Splash-Screen
• @capacitor/status-bar: Stile die Geräte-Status-Leiste
• @capacitor/preferences: Schlüssel-Wert-Speicher (wie localStorage, aber native)

3. Initialisiere Capacitor mit deinen Projekt-Daten:

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

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

4. Erstelle oder aktualisiere 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. Installiere native Plattformen:

bun add @capacitor/ios @capacitor/android

6. Füge die native Plattform-Ordner hinzu:

bunx cap add ios
bunx cap add android

Capacitor erstellt ios und android Ordner am Root deines Projekts, die die native Projekte enthalten.

To build the Android project, you need Android Studiofür iOS benötigen Sie einen Mac mit Xcode.

7. Ihre Projektdateien synchronisieren:

bun run mobile

Dies läuft Ihre benutzerdefinierte Skript aus, das die statische Nuxt-Build erzeugt und die Dateien mit den nativen Plattformen synchronisiert.

Erstellen und Bereitstellen von nativen Apps

To build and deploy your native mobile app, follow these steps:

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

1. Öffnen Sie die native Projekte:

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 warten Sie, bis das Projekt bereit ist, und klicken Sie dann auf die Schaltfläche 'Ausführen', um die App auf einem verbundenen Gerät oder Emulator zu deployen.

• In Xcode stellen Sie Ihre Signierungskonto ein, um die App auf einem echten Gerät zu deployen. Wenn Sie dies noch nicht getan haben, führt Xcode Sie durch den Prozess (beachten Sie, dass Sie sich im Apple Developer Program anmelden müssen). Sobald Sie eingerichtet sind, klicken Sie auf die Schaltfläche 'Play', um die App auf Ihrem verbundenen Gerät auszuführen.

Herzlichen Glückwunsch! Sie haben Ihre Nuxt-Web-App erfolgreich 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 können Sie von Live-Neustarten profitieren, um Änderungen sofort auf Ihrem Mobilgerät zu sehen. Um diese Funktion zu aktivieren, folgen Sie diesen Schritten:

1. Finden Sie Ihre lokale IP-Adresse:

• Auf macOS führen Sie den folgenden Befehl im Terminal aus:

  ipconfig getifaddr en0

• Auf Windows führen Sie:

  ipconfig

  Suchen Sie nach der IPv4-Adresse in der Ausgabe.

2. Aktualisieren Sie 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 nativen Projekt:

bunx cap copy

Die copy Der Befehl kopiert das Web-Ordner und Konfigurationsänderungen in das native Projekt ohne das gesamte Projekt zu aktualisieren.

4. Starte deinen Nuxt Dev-Server und rebuild in Xcode/Android Studio:

bun run dev

Jetzt werden die Änderungen an Ihrer Nuxt-App automatisch in der mobilen App aktualisiert.

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

Mit Capacitor-Plugins

Capacitor-Plugins ermöglichen Ihnen, native Gerätefunktionen von Ihrer Nuxt-Anwendung aus zu nutzen. Lassen Sie uns sehen, wie man das Teilen-Plugin als Beispiel verwendet:

1. Installieren Sie das Teilen-Plugin:

bun add @capacitor/share

2. Create or update a page to use the Share plugin. In Nuxt 4, pages go 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. Sync the changes with the native project:

bun run mobile

Oder synchronisieren Sie einfach ohne Neubau:

bunx cap sync

4. Wiederbauen und auf Ihrem Gerät ausführen.

Nun erscheint bei einem Klick auf den „Jetzt teilen!“-Button 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 häufige iOS-Anzeigefehler beheben, die zu horizontaler Überschreitung oder gekürzten sicheren Bereichen führen.

Natürlicher Anwendungsdesign mit Capgo-Native-Navigation und -Übergängen

Ich habe Jahre lang 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:

• @capgo/capacitor-native-Navigation --- native Navbar, Liquid Glass Tabbar auf iOS und eine verschwommene Tabbar-Style auf Android. Ihr Nuxt-Router hält die Routenstatus; der Plugin besitzt die native Chrome.
• @capgo/capacitor-Übergänge — Seitenübergänge im Ionic-Stil und iOS-Rückblättern am Rand in der WebView-Schicht, ohne Ionic-UI zu übernehmen.

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

Render a Liquid Glass tab bar (iOS uses system-owned rendering; Android uses a blurred WebView backdrop):

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>

Wrap routed Pages in cap-router-outlet, cap-pageund cap-contentund rufen Sie setDirection('forward') oder setDirection('back') Bevor Sie navigieren. Duplizieren Sie keine Web-Über- oder Fußzeilen, wenn native Navigation diese Oberflächen besitzt.

Siehe die vollständigen Anleitungen: Mit @capgo/capacitor-native-Navigation und Mit @capgo/capacitor-Übergänge.

Sichere Bereiche mit Tailwind

For device safe areas in Tailwind CSS, use @capgo/tailwind-capacitor (publikiert als) tailwind-capacitor auf npm veröffentlicht). Es bietet safe-areas Benutzbarkeiten 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 Importierung im CSS-File bei, das von nuxt.config.ts.

Wenden Sie sich an Werkzeuge wie pt-safe, pb-safe, und px-safe anstatt das zu verstreuen env(safe-area-inset-*) manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Nuxt-Konfiguration fehlt, erstellen Sie einen PR auf GitHub.

iOS-Layoutprobleme 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 den Viewport-Tag allein nicht aus. Arbeiten Sie durch diese Kontrollen in der Reihenfolge.

Make sure the viewport meta tag is applied correctly

In nuxt.config.ts, setzen Sie den Viewport über app.head:

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

Handle iOS safe area from one root wrapper only

Create a single app shell and apply safe area padding there — not in multiple nested components:

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

Umfasst alle Seite-Inhalte innerhalb von .app-shell Doppeltes sicherheitsrelevante Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitor kannst du denselben Padding mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Shell ausdrücken.

Setze Capacitor iOS contentInset auf never first

erst capacitor.config.ts, bevorzugt native Inset deaktivieren und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css'Besitzt man das sichere Bereich:

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

Mischen Sie Capacitor’s automatische Inhaltsabstände mit CSS env(safe-area-inset-*) padding is a common cause of double spacing.

Finden Sie das überfließende 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 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,
  }));

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

Zusammenfassung

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

Wat haben Sie erreicht:

• Konfiguriert Nuxt für statische Erzeugung
• Fügte Capacitor 8 mit wichtigen Plugins hinzu
• Erstellte und deployte auf iOS- und Android-Emulatoren
• Aktivierte Live-Reload für Entwicklung
• Löste häufige iOS-Ansichten (viewport, sichere Bereich, Überlauf) aus
• Fügte native anfühlfende UI mit Capgo Native Navigation und Transitions hinzu

Nächste Schritte:

• Einstellungen Capgo für über-einige-Air-Updates ohne Wiederabgabe im App-Store
• Fügen Sie weitere native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzu
• Konfigurieren Sie App-Ikonen und Splash-Screens für die Produktion
• Vorbereiten Sie Ihre App für die Einreichung bei App Store und Google Play

Starten Sie ein neues Projekt? Überprüfen Sie Ein Nuxt-Mobil-App von Grund auf aufbauen für eine geführte Anleitung.

Ressourcen

• Nuxt-Dokumentation
• Capacitor 8 Dokumentation
• @capgo/capacitor-native-Navigation — Liquid Glass-Tastenleiste und native Chrome
• @capgo/capacitor-Übergänge — nativ anfühlfende Seite-Übergänge
• @capgo/tailwind-capacitor — Tailwind-sichere-Bereichs-Utilities für Capacitor
• Capgo - Live-Updates für Capacitor-Apps

Learn how Capgo can help you build better apps faster, Registrieren Sie sich für ein kostenloses Konto heute.

Weitermachen von Convert Your Nuxt App zu iOS & Android mit Capacitor 8

Wenn Sie bereits Convert Your Nuxt App zu iOS & Android mit Capacitor 8 um native Plugin-Arbeit zu planen, mit ihr zu verbinden Capgo Plugin-Verzeichnis zur Produktionsablauf in Capgo Plugin Directory Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetail in Hinzufügen oder Aktualisieren von Plugins Ionische Unternehmens-Plugin-Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen, und Capgo nativee native Builds zur Produktionsablauf in Capgo Native Builds.