Ein Next.js 15-Mobil-App von Grund auf mit Capacitor 8 erstellen

Einführung

Möchten Sie eine mobile Anwendung 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 Paketieren als native iOS- und Android-Anwendungen mit Capacitor 8.

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

Zeit, die benötigt wird: ~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
Nativ-Apps für iOS und Android
Live-Reload-Entwicklungssetup

Haben Sie bereits eine Next.js-Anwendung? Überprüfen Sie stattdessen: Ihre Next.js-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 für macOS, für die iOS-Entwicklung)
Android Studio (für die 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 (@/*)

Navigieren Sie zu Ihrem Projekt:

cd my-mobile-app

Schritt 2: Konfigurieren Sie Next.js für statische Exporte

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-Servicerequirement
images: { unoptimized: true } — Deaktiviert die Next.js-Bildoptimierung (erfordert einen Server)
trailingSlash: true — Stellt sicher, dass die Routing in der 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 Build:

bun run build

Sie sollten ein out Verzeichnis mit Ihren statischen Dateien.

Schritt 4: Installieren Sie Capacitor 8

Installieren Sie die Kernpaket von Capacitor:

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

Installieren Sie wesentliche 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-Lebenzyklus (Vordergrund/Hintergrund, tiefere Links)
@capacitor/keyboard — Steuern Sie das Verhalten der Tastatur
@capacitor/splash-screen — Kontrolle des nativen Splash-Screens
@capacitor/status-bar — Die Gerätestatusleiste anpassen
@capacitor/vorlieben — Schlüssel-Wert-Speicherung (wie localStorage, aber native)

Schritt 5: Capacitor initialisieren

Capacitor mit Ihren Projekt-Daten initialisieren:

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 Ihrer Anwendungs-ID (umgekehrte Domänennotation)

Dies erstellt capacitor.config.ts. Aktualisieren Sie es mit der 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: Native Plattformen hinzufügen

Die Plattform-Pakete installieren:

bun add @capacitor/ios @capacitor/android

Erstellen Sie die nativen Projekte:

bunx cap add ios
bunx cap add android

Dies erstellt ios und android Verzeichnisse, die die nativen Projekte enthalten.

Schritt 7: Erstellen und Ausführen

Bauen Sie Ihr Projekt und synchronisieren Sie es mit den nativen 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, synchronisiert zu sein
Wählen Sie ein Emulator aus dem Geräte-Auswahlfeld
Klicken Sie auf die Ausführungs-Schaltfläche 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

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 in 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 sofort neu geladen.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirm

Lassen Sie uns eine einfache, mobilen-freundliche Startseite erstellen. Aktualisieren 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: Fügen Sie die Verarbeitung des sicheren Bereichs hinzu

Mobile Geräte haben Notcher, Heimindikatoren und Statusleisten. Fügen Sie die Verarbeitung des sicheren Bereichs mit Tailwind hinzu.

Aktualisieren 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 Next.js-Mobilanwendung. Hier sind die nächsten Schritte:

Wichtige Einrichtungen

App-Icons: Ersetzen Sie die Standardicons in ios/App/App/Assets.xcassets und android/app/src/main/res
Splash-Screen: Anpassen in native Projekten oder verwenden @capacitor/splash-screen __CAPGO_KEEP_0__
Deep Links: Konfigurieren Sie die URL-Schemas 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, die Integration von Konsta UI für native aussehende iOS/Android-Komponenten:

bun add konsta

Über-ein-Netzwerk-Updates

Einrichten Capgo Um Updates ohne Wiederinbetriebnahme des App-Stores zu pushen:

bunx @capgo/cli init

Fehlersuche

Build fehlschlägt mit „Cannot find module“ Ausführen bun install und versuchen Sie es erneut.

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

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 Anpassung bun run mobile nach der Anpassung. 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.

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