Nuxt App mit Capacitor 8 für iOS & Android konvertieren

Einführung

Have an existing Nuxt web application? In this guide, you’ll learn how to transform it into native iOS and Android mobile apps using Capacitor 8 — die neueste Version mit verbesserter Performance und neuen Features.

Capacitor hüllt deine Web-App in einen nativen Container. So erhältst du Zugriff auf Device-APIs wie Kamera, Filesystem und Push-Notifications, während dein bestehender Vue-Code erhalten bleibt. Im Gegensatz zu Flutter oder React Native musst du nichts umschreiben – dein Nuxt code läuft einfach so weiter.

Das lernst du:

Konfiguration deiner Nuxt-App für Static Generation
Hinzufügen von Capacitor 8 mit essenziellen nativen Plugins
Build und Test auf iOS- und Android-Simulatoren
Live Reload für schnelleres Development aktivieren
Häufige iOS-Layout-Probleme lösen (Viewport, Safe Area, Horizontal Overflow)
Native UI mit Capgo Native Navigation und Transitions

Möchtest du ein neues Projekt von Grund auf starten? Schau dir unseren Guide an zu: Eine Nuxt Mobile App von Grund auf neu bauen.

Vorteile von Nuxt und Capacitor

Code Wiederverwendbarkeit: Teile deine Vue-Komponenten und Logik zwischen Web- und Mobile-Apps.
Performance: Nuxts statische Generierung erstellt optimierte Bundles, die perfekt für Mobile sind.
Native Funktionen: Greife über Capacitor Plugins auf Gerätefunktionen wie Kamera, Geolocation und Filesystem zu.
Einfachere Entwicklung: Nutze vertraute Vue/Nuxt-Patterns, ohne native Entwicklung lernen zu müssen.

Voraussetzungen

Before you begin, make sure you have:

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

Deine Nuxt-App für Mobile konfigurieren

Der erste Schritt ist die Konfiguration deiner Nuxt-App für Static Site Generation. Capacitor benötigt statische HTML/JS/CSS-Dateien, um sie in die Native Build einzubinden.

Stelle sicher, dass deine package.json das generate-Script 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 du serverseitige Features nutzt (API Routes, Server-Middleware usw.), musst du diese auf clientseitige Alternativen oder externe APIs umstellen.

Teste die statische Generierung mit:

bun run generate

Du solltest einen .output/public Ordner mit deinen statischen Dateien sehen. Das ist es, was Capacitor in deine native App bündelt.

Capacitor 8 zu deinem Projekt hinzufügen

Um deine Nuxt-App in einen nativen Mobile-Container zu packen, folge diesen Schritten:

Installiere Capacitor Core und CLI:

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

Installiere die gängigen Capacitor Plugins, die du wahrscheinlich brauchst:

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

Diese Plugins bieten essenzielle Features:

@capacitor/app: App-Lifecycle-Events verwalten (Foreground/Background, Deep Links)
@capacitor/keyboard: Tastaturverhalten auf Mobilgeräten steuern
@capacitor/splash-screen: Native Splash Screen verwalten
@capacitor/status-bar: Device Status Bar stylen
@capacitor/preferences: Key-Value-Storage (wie localStorage, aber nativ)

Initialisiere Capacitor mit deinen Projektdaten:

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

Ersetze my-app mit deinem App-Namen und com.example.myapp mit deiner App-ID (Reverse-Domain-Notation).

Erstelle oder aktualisiere die capacitor.config.ts Datei mit der passenden 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;

Native Plattformen installieren:

bun add @capacitor/ios @capacitor/android

Native-Plattform-Ordner hinzufügen:

bunx cap add ios
bunx cap add android

Capacitor erstellt ios und android Ordner im Projekt-Root, die die nativen Projekte enthalten.

Um das Android-Projekt zu builden, benötigst du Android Studio. Für iOS brauchst du einen Mac mit Xcode.

Projekt bauen und synchronisieren:

bun run mobile

Hier wird dein Custom Script ausgeführt, das den statischen Nuxt-Build erstellt und die Dateien mit den nativen Plattformen synchronisiert.

Native Apps bauen und deployen

Um deine native Mobile App zu bauen und zu deployen, folge diesen Schritten:

Für die iOS-Entwicklung benötigst du Xcode installiert. Für Android-Apps benötigst du Android Studio installiert. Wenn du deine App zudem in den App Stores veröffentlichen willst, musst du dich für das Apple Developer Program (iOS) bzw. die Google Play Console (Android) anmelden.

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

App bauen und ausführen:

android-studio-run

Warten Sie in Android Studio, bis das Projekt bereit ist, und klicken Sie dann auf „Run“, um die App auf einem verbundenen Gerät oder Emulator zu deployen.

xcode-run

Richten Sie in Xcode Ihr Signing-Account ein, um die App auf einem echten Gerät zu deployen. Falls Sie das noch nicht gemacht haben, führt Sie Xcode durch den Prozess (beachten Sie, dass Sie im Apple Developer Program angemeldet sein müssen). Klicken Sie nach der Einrichtung auf „Play“, um die App auf Ihrem verbundenen Gerät auszuführen.

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

Aber Moment, es gibt während der Entwicklung auch einen noch schnelleren Weg…

Capacitor Live Reload

Während der Entwicklung können Sie Live Reload nutzen, um Änderungen sofort auf Ihrem mobilen Gerät zu sehen. Um diese Funktion zu aktivieren, folgen Sie diesen Schritten:

Ermitteln Sie Ihre lokale IP-Adresse:

Führen Sie unter macOS diesen Befehl im Terminal aus:
```
ipconfig getifaddr en0
```
Unter Windows ausführen:
```
ipconfig
```
Suchen Sie in der Ausgabe nach der IPv4-Adresse.

Aktualisiere dein capacitor.config.ts um auf deinen Development-Server 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;

Ersetze YOUR_IP_ADDRESS mit deiner lokalen IP-Adresse (z. B. 192.168.1.100).

Übernimm die Änderungen in dein natives Projekt:

bunx cap copy

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

Starte deinen Nuxt Dev-Server und baue in Xcode/Android Studio neu:

bun run dev

Wenn du jetzt Änderungen an deiner Nuxt-App vornimmst, lädt sich die Mobile App automatisch neu und übernimmt diese Änderungen.

Hinweis: Wenn du neue Plugins installierst oder native Dateien änderst, musst du das native Projekt neu bauen, da Live Reloading nur für Web-code-Änderungen gilt.

Capacitor Plugins verwenden

Capacitor Plugins ermöglichen dir den Zugriff auf native Device-Funktionen aus deiner Nuxt-App. Schauen wir uns an, wie man den Share-Plugin als Beispiel nutzt:

Installiere das Share-Plugin:

bun add @capacitor/share

Erstelle oder aktualisiere eine Seite, um das Share-Plugin zu nutzen. In Nuxt 4 liegen die Pages 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>

Synchronisiere die Änderungen mit dem nativen Projekt:

bun run mobile

Oder synchronisiere einfach ohne Rebuild:

bunx cap sync

Rebuild durchführen und die App auf deinem Device starten.

Wenn du jetzt auf den „Share now!“-Button klickst, öffnet sich der native Share-Dialog.

Als Nächstes kannst du die App auf iOS und Android mit Capgo Navigation und Transitions nativer wirken lassen und typische iOS-Layoutprobleme beheben, die horizontalen Overflow oder abgeschnittene Safe Areas verursachen.

Ich arbeite schon seit Jahren mit Ionic um plattformübergreifende Apps zu bauen, aber die Integration mit Nuxt ist hacky und selten lohnenswert, wenn du bereits Tailwind CSS.

Für ein natives Mobile-Feeling in einer Nuxt + Capacitor App solltest du Capgo Plugins statt reiner Web-UI-Kits wie Konsta UI nutzen:

@capgo/capacitor-native-navigation — native Navbar, Liquid Glass Tab Bar auf iOS und ein Blur-Effekt für die Tab Bar auf Android. Dein Nuxt-Router behält den Route-State; das Plugin übernimmt das native UI-Chrome.
@capgo/capacitor-transitions — Page Transitions im Ionic-Stil und iOS Edge Swipe-Back in der WebView-Ebene, ohne das Ionic UI zu übernehmen.

Beides installieren:

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

Konfiguriere die native Navigation mit dem CSS Inset Mode, damit Web-Content die nativen Bars berücksichtigt:

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

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

Rendere eine Liquid Glass Tab Bar (iOS nutzt systemeigenes Rendering; Android nutzt einen geblurrten 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üge native Page Transitions in deine App Shell ein:

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

Umschließe geroutete Seiten mit cap-router-outlet, cap-page, und cap-content, und rufe setDirection('forward') oder setDirection('back') bevor du navigierst. Dupliziere keine Web-Header oder -Footer, wenn die native Navigation diese Bereiche bereits übernimmt.

Hier findest du die vollständigen Guides: Verwendung von @capgo/capacitor-native-navigation und Verwendung von @capgo/capacitor-transitions.

Safe Areas mit Tailwind

Verwende für Device Safe Areas in Tailwind CSS @capgo/tailwind-capacitor (veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Utilities und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

Unter 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 behalte diesen Import in der CSS-Datei, die von nuxt.config.ts.

Nutze Utilities wie pt-safe, pb-safe, und px-safe anstatt alles manuell env(safe-area-inset-*) manuell erstellt wurde. Das Projekt wird aktiv weiterentwickelt – falls etwas für dein Nuxt-Setup fehlt, eröffne einen PR auf GitHub.

iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontaler Overflow)

Wenn Inhalte auf iOS abgeschnitten, verschoben oder horizontal scrollbar wirken, hilft es meist nicht, mehr overflow-x: hidden hinzuzufügen oder nur das Viewport-Tag zu ändern. Gehe diese Checks der Reihe nach durch.

Stelle sicher, dass das Viewport-Meta-Tag korrekt angewendet wird

Unter nuxt.config.ts, setze den Viewport über app.head:

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

iOS Safe Area nur von einem Root-Wrapper aus handhaben

Erstelle eine einzige App-Shell und wende dort das 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);
}

Umschließe den gesamten Seiteninhalt mit .app-shellDoppeltes Safe-Area-Padding in Headern, Modals und Layout-Wrappern lässt das UI oft abgeschnitten oder zu groß wirken.

Mit @capgo/tailwind-capacitor, kannst du dasselbe Padding mit Utilities wie pt-safe pb-safe px-safe in dieser einen Shell ausdrücken.

Setze Capacitor iOS `contentInset` zu `never` zuerst

Unter capacitor.config.ts, deaktiviere lieber native Insets und überlasse CSS (oder der Native Navigation contentInsetMode: 'css') die Safe Area:

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

Kombination von Capacitor’s automatischen Content Insets mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.

Das tatsächlich überlaufende Element finden

Der übliche Übeltäter ist ein Element mit 100vw, Tailwind w-screen, einer festen Pixelbreite oder einem großen min-width.

Im 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 w-screen mit w-full wann immer möglich. Viele Probleme mit horizontalem Overflow entstehen durch 100vw / w-screen, doppeltes Safe-Area-Padding oder einen Container mit fester Breite – nicht durch das Viewport-Meta-Tag selbst.

Fazit

Du hast deine bestehende Nuxt-Web-App erfolgreich mit Capacitor 8 in native iOS- und Android-Apps umgewandelt. Dein Vue-Code läuft nun nativ auf mobilen Geräten und hat Zugriff auf Device-APIs.

Das hast du erreicht:

Nuxt für Static Generation konfiguriert
Capacitor 8 mit essenziellen Plugins hinzugefügt
Build und Deployment auf iOS- und Android-Simulatoren durchgeführt
Live Reload für die Entwicklung aktiviert
Häufige iOS-Layoutprobleme behoben (Viewport, Safe Area, Overflow)
Native-Feeling UI mit Capgo Native Navigation und Transitions hinzugefügt

Nächste Schritte:

Einrichten Capgo für Over-the-Air Updates ohne App Store Resubmission
Weitere native Plugins wie Camera, Geolocation oder Push Notifications hinzufügen
App-Icons und Splash Screens für die Produktion konfigurieren
App für die Einreichung im App Store und bei Google Play vorbereiten

Ein komplett neues Projekt starten? Schau dir an: Nuxt Mobile App von Grund auf neu bauen für eine Schritt-für-Schritt-Anleitung.

Ressourcen

Nuxt Dokumentation
Capacitor 8 Dokumentation
@capgo/capacitor-native-navigation — Liquid Glass Tab Bar und native Bedienelemente
@capgo/capacitor-transitions — Page Transitions, die sich nativ anfühlen
@capgo/tailwind-capacitor — Tailwind Safe-Area-Utilities für Capacitor
Capgo - Live Updates für Capacitor Apps

Erfahren Sie, wie Capgo Ihnen hilft, schneller bessere Apps zu bauen, Registrieren Sie sich für ein kostenloses Konto noch heute.

Weiterlesen: Konvertiere deine Nuxt App zu iOS & Android mit Capacitor 8

Wenn du es nutzt Deine Nuxt-App mit Capacitor 8 für iOS & Android konvertieren Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails unter „Plugins hinzufügen oder aktualisieren“, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen und Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds.