Build a Nuxt Mobile App from Scratch mit Capacitor 8

Einführung

Möchten Sie eine mobile App mit Nuxt von Grund auf erstellen? Diese Anleitung führt Sie durch die Erstellung 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, indem es verwendet wird Capacitor 8.

Mit dieser Anleitung haben Sie am Ende eine funktionierende mobile App, 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:

Eine neue Nuxt 4-Projekt mit der neuesten Verzeichnisstruktur
Statistische Generierungskonfiguration für mobile Geräte
Capacitor 8 mit wichtigen Plugins
Native iOS- und Android-Anwendungen
Live-Reload-Entwicklungsumgebung

Haben Sie bereits eine Nuxt-Anwendung? Überprüfen Sie stattdessen Ihre Nuxt-Anwendung auf Mobilgeräte 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 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 Anwendung 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

Update Ihre 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 Verzeichnis mit Ihren statischen Dateien sehen. .output/public Schritt 4: Installieren Sie __CAPGO_KEEP_0__ 8

Installieren Sie die Kern-Pakete von Capacitor:

Install the Capacitor core packages:

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

Was diese Plugins tun:

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

@__CAPGO_KEEP_0__/app

@capacitor/app @__CAPGO_KEEP_0__/keyboard
@capacitor/keyboard — Tastaturenbetonsteuerung
@capacitor/splash-screen — Kontrolle der native Splash-Screen
@capacitor/status-bar — Schlüssel-Wert-Speicher (wie localStorage, aber native)
Schritt 5: Initialisiere capacitor Initialisiere __CAPGO_KEEP_0__ mit Ihren Projekt-Daten:

Step 5: Initialize Capacitor

Initialize Capacitor with your project details:

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

mit Ihrer App-ID (umgekehrte Domänennotation)

"My Mobile App" @__CAPGO_KEEP_0__/preferences
com.example.mymobileapp — Steuere die Tastaturverhalten

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: Fügen Sie Native Plattformen hinzu

Installieren Sie die Plattform-Pakete:

bun add @capacitor/ios @capacitor/android

Erstellen 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

Bauen Sie Ihr Projekt und synchronisieren Sie es mit den native 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 ein Simulator aus dem Geräte-Auswahlfeld
Klicken Sie auf die Play-Taste oder drücken Sie Cmd + R

In Android Studio:

Warten Sie, bis Gradle fertig ist
Wählen Sie einen Emulator aus dem Geräte-Auswahlfeld
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;

Starten Sie den Entwicklungs-Server und kopieren Sie die Konfiguration in die native Umgebung:

bun run dev &
NODE_ENV=development bunx cap copy

Rebuild in Xcode/Android Studio

Nun werden Änderungen an Ihrem Nuxt code auf dem Gerät live geladen.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirm

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

Um die Gestaltung zu aktivieren, fügen Sie Tailwind CSS Ihrem Projekt hinzu:

bun add tailwindcss @tailwindcss/vite

Erstellen 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()],
  },
});

Schritt 11: Fügen Sie den Teilen-Plugin hinzu 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;
}

Erstellen

bun add @capacitor/share

Aktualisieren app/pages/index.vue um den Share-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 erstellen:

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:

Wichtige Einstellungen

App-Ikone: Ersetzen Sie die Standard-Ikone in ios/App/App/Assets.xcassets und android/app/src/main/res
Splash-Screen: Anpassen in native Projekten oder verwenden @capacitor/splash-screen Konfiguration
Tiefe Links: Konfigurieren Sie die URL-Schemata für Ihre App

Hinzufügen Sie weitere Funktionen

Kamera: bun add @capacitor/camera
Ortung: bun add @capacitor/geolocation
Push-Benachrichtigungen: bun add @capacitor/push-notifications oder @capgo/capacitor-firebase-messaging Entscheiden Sie sich für Appflow, um Ihre App zu erstellen, oder nutzen Sie eine andere Lösung?
Entscheiden Sie sich für Capawesome, um Ihre App zu erstellen, oder nutzen Sie eine andere Lösung? bun add @capacitor/filesystem

Entscheiden Sie sich für eine Lösung, die Ihren Anforderungen entspricht, oder nutzen Sie unsere Beratungsdienste, um die beste Lösung für Ihre App zu finden?

Verwenden Sie Capgo-Plugins anstatt Konsta UI für ein nativ anführendes Mobile-Gefühl:

@capgo/capacitor-native-Navigation — Liquid Glass-Tasteleiste und nativer Navbar
@capgo/capacitor-Übergänge — natürliche 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

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

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

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr oder passen Sie den Viewport-Tag allein normalerweise nicht aus. overflow-x: hidden Überprüfen Sie diese Schritte in der Reihenfolge.

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

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

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

Behandeln Sie das iOS-Safe-Area aus einer einzigen Root-Wrapper

Erstellen Sie eine einzelne 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 von .app-shellDoppelte Safe-Area-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

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

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

In capacitor.config.ts, bevorzugen Sie native eingefrorene Einstellungen und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') den sicheren Bereich übernehmen:

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

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

Finden Sie das tatsächlich überschüssige 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, 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-screen, dupliziertem sicheren Bereich-Puffer oder einem fixbreiten Container — nicht von der Viewport-Meta-Tags selbst.

Over-the-Air-Updates

Setzen Sie Capgo um Updates ohne App-Store-Neuabrechnung zu pushen:

bunx @capgo/cli init

Schulung

Der Build scheitert mit „Cannot find module“ Ausführen bun install und probieren Sie es erneut.

iOS: „Kein Signierungsidentität gefunden“ Öffnen Sie Xcode, gehen Sie zu Signierung und Fähigkeiten und wählen Sie Ihr Entwicklungsteam.

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 konfiguriert haben nitro: { preset: 'static' } in nuxt.config.ts und ausführen bun run generate.

Ressourcen

Bereit, Ihre App zu verschicken? Erfahren Sie, wie Capgo Ihnen dabei helfen kann, Updates schneller zu liefern — Registrieren Sie sich für ein kostenloses Konto Heute.

Fortsetzen Sie mit 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 for the product workflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub Aktionen-Integration für die Implementierungsdetails in GitHub Aktionen-Integration.

Build a Nuxt Mobile App from Scratch with Capacitor 8