Mit Capacitor 8 einen Next.js Mobile App von Grund auf aufbauen

Einführung

Möchten Sie eine mobile App mit Next.js von Grund auf erstellen? Diese Anleitung führt Sie durch das Erstellen eines brandneuen Next.js 15-Projekts, das von Anfang an für mobile Entwicklung konfiguriert ist, und das dann als native iOS- und Android-Anwendungen verpackt wird mithilfe von Capacitor 8.

Am Ende dieser Anleitung werden Sie eine funktionierende mobile App haben, die auf Simulatoren läuft, die Sie weiterentwickeln und schließlich auf dem App Store und Google Play veröffentlichen können.

Zeitaufwand: ~30 Minuten

Was Sie bauen werden:

Ein neues Next.js 15-Projekt mit App Router
Statik-Export-Konfiguration für Mobilgeräte
Capacitor 8 mit wesentlichen Plugins
Native iOS- und Android-Apps
Live-Reload-Entwicklungssetup

Haben Sie bereits eine Next.js-Anwendung? Überprüfen Sie Ihre Next.js App auf Mobilgeräte umwandeln anstatt.

Voraussetzungen

Stellen Sie sicher, dass Sie diese installiert haben:

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 Next.js-Projekt

Beginnen Sie mit der Erstellung eines frischen Next.js 15-Projekts:

bunx create-next-app@latest my-mobile-app

Wenn Sie dazu aufgefordert werden, wählen Sie diese Optionen:

TypeScript: Ja (empfohlen)
ESLint: Ja
Tailwind CSS: Ja (empfohlen für mobile Styling)
src/ Verzeichnis: Ja
App Router: Ja (empfohlen)
Import Alias: Standard (@/*)

Navigiere zu deinem Projekt:

cd my-mobile-app

Schritt 2: Konfiguriere Next.js für statische Export

Capacitor erfordert statische HTML/JS/CSS-Dateien. Konfigurieren Sie Next.js für statische Exporte, indem Sie next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

Warum diese Einstellungen?

output: 'export' — Erzeugt statisches HTML anstatt eine Node.js-Serveranforderung zu benötigen
images: { unoptimized: true } — Deaktiviert die Next.js-Bildoptimierung (erfordert einen Server)
trailingSlash: true — Stellt sicher, dass die Routingfunktion im nativen WebView ordnungsgemäß funktioniert

Schritt 3: Hinzufügen von mobilen Skripten

Aktualisieren Sie Ihre package.json mit mobilen Entwicklungs-Skripten:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Testen Sie die Veröffentlichung:

bun run build

Sie sollten ein out Verzeichnis mit Ihren statischen Dateien sehen.

Schritt 4: Installieren Sie Capacitor 8

Installieren Sie die Capacitor Kernpaket:

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

Installieren Sie wichtige Plugins, die 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 — Ereignisse im App-Lebenszyklus (Vordergrund/Hintergrund, tiefere Links)
@capacitor/keyboard — Tastaturverhalten steuern
@capacitor/splash-screen — Kontrolle des nativen Splash-Screens
@capacitor/status-bar — Stilen Sie die Geräte-Statusleiste
@capacitor/preferences — Schlüssel-Wert-Speicher (wie localStorage, aber native)

Schritt 5: Initialisieren Sie Capacitor

Initialisieren Sie Capacitor mit Ihren Projekt-Daten:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

Ersetzen:

"My Mobile App" mit dem Namen Ihres Anwendungs-Displays
com.example.mymobileapp mit der ID Ihres Apps (umgekehrte Domänennotation)

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: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

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

Erstellen Sie Ihr Projekt und synchronisieren Sie es mit den native Plattformen:

bun run mobile

In iOS Simulator öffnen:

bun run mobile:ios

Oder Android-Emulator:

bun run mobile:android

In Xcode (iOS):

Wählen Sie einen 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, sich zu synchronisieren
Wählen Sie einen Emulator aus dem Geräte-Auswahlfeld
Klicken Sie auf die Ausführen-Schaltfläche oder drücken Sie Shift + F10

Schritt 8: Einrichten von Live Reload

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

Erstellen Sie eine Entwicklungskonfiguration Capacitor. Fügen Sie zu capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  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: 'out',
  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 zu native:

bun run dev &
NODE_ENV=development bunx cap copy

Rebuild in Xcode/Android Studio

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

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirmseite

Lassen Sie uns eine einfache, mobilen-freundliche Startseite erstellen. Aktualisieren Sie src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

    // Handle back button on Android
    const backHandler = App.addListener('backButton', ({ canGoBack }) => {
      if (!canGoBack) {
        App.exitApp();
      } else {
        window.history.back();
      }
    });

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="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">
          Learn More
        </button>
      </div>
    </main>
  );
}

Schritt 10: Hinzufügen von Safe Area-Handling

Mobile Geräte haben Notch, Home-Indikatoren und Statusleisten. Fügen Sie Safe Area-Handling mit Tailwind hinzu.

Aktualisierung src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

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

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

Projektstruktur

Ihr Projekt sollte jetzt wie folgt aussehen:

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

Nächste Schritte

Sie haben jetzt eine funktionierende mobile App mit Next.js. 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 Sie in native Projekten oder verwenden Sie @capacitor/splash-screen config
Tiefen Links: Konfigurieren Sie URL-Schemata für Ihre App

Mehr Funktionen hinzufügen

Kamera: bun add @capacitor/camera
Standort: bun add @capacitor/geolocation
Push-Benachrichtigungen: bun add @capacitor/push-notifications
Dateisystem: bun add @capacitor/filesystem

Benutzeroberflächenvervollkommnung

Überlegen Sie, ob Sie Konsta UI für native aussehende iOS/Android-Komponenten:

bun add konsta

Over-the-Air-Updates

Einrichten Capgo um Updates ohne App-Store-Neuveröffentlichung zu pushen:

bunx @capgo/cli init

Fehlerbehebung

Build fehlt mit “Cannot find module” Ausführen bun install und versuchen Sie es erneut.

iOS: “Kein Signierungsidentität gefunden” Öffnen Sie Xcode, gehen Sie zu Signing & Capabilities, 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 nach der Änderung bun run mobile die Anwendung neu gestartet haben. Für Live-Neustart überprüfen Sie, ob die IP-Adresse korrekt ist und der Entwicklungs-Server läuft.

Ressourcen

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

Weitermachen Sie von Build a Next.js Mobile App von Grund auf mit Capacitor 8

Wenn Sie __CAPGO_KEEP_0__ verwenden Erstellen Sie von Grund auf eine Mobile App mit Next.js mit Capacitor 8 um die CI/CD-Automatisierung zu planen, verbinden Sie sie 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 für den Produktworkflow in Capgo Integrations CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration GitHub Actions Integration für die Implementierungsdetails in GitHub Actions-Integration.

Ein Next.js-Mobilanwendung von Grund auf mit Capacitor 8 erstellen