Ein Next.js Mobile App von Grund auf mit Capacitor 8 erstellen

Einleitung

Wollen Sie eine mobile App mit Next.js von Grund auf aufbauen? Diese Anleitung führt Sie durch die Erstellung einer brandneuen Next.js 15-Projekt, das von Anfang an für mobile Geräte konfiguriert ist, und das dann als native iOS- und Android-Apps verpackt wird. Capacitor 8.

Am Ende dieser Anleitung haben Sie 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 Next.js 15-Projekt mit App Router
Statistische Exportkonfiguration für mobile Geräte
Capacitor 8 mit wesentlichen Plugins
Native iOS- und Android-Apps
Live-Reload-Entwicklungsumgebung

Bereits ein Next.js-Projekt vorhanden? Überprüfen Sie Ihre Next.js App auf Mobilgeräte umwandeln anstatt.

Voraussetzungen

Stellen Sie sicher, dass diese installiert sind:

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

Wählen Sie bei der Aufforderung diese Optionen aus:

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 Exportierung

Capacitor erfordert statische HTML/JS/CSS-Dateien. Konfiguriere Next.js für statische Exportierung, indem du 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: Füge mobile Skripte hinzu

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 Verzeichnis mit Ihren statischen Dateien sehen. out Schritt 4: Installieren Sie __CAPGO_KEEP_0__ 8

Installieren Sie die Capacitor-Kernpakete:

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 — Gestalte das Geräte-Status-Leiste
@capacitor/preferences — Schlüssel-Wert-Speicherung (wie localStorage, aber native)

Schritt 5: Initialisiere Capacitor

Initialisiere 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 Apps
com.example.mymobileapp mit der App-ID (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: Hinzufügen von Native Plattformen

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: Bauen 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, die Synchronisierung durchzuführen
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

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 die native Umgebung:

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 mit Hot-Reload aktualisiert.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirmoberfläche

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 von Safe Areas hinzu

Mobile Geräte haben Notch, Heimindikatoren und Statusleisten. Fügen Sie die Verarbeitung von Safe Areas 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-Mobil-App. Hier sind die nächsten Schritte:

Wichtige Einstellungen

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

Mehr Funktionen hinzufügen

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

Natives UI und Übergänge

Verwenden Sie Capgo-Plugins anstelle von Konsta UI für ein nativ anführendes Mobilgeräte-Erlebnis:

@capgo/capacitor-native-navigation — Liquid Glass-Tasteleiste und nativer Navbar
@capgo/capacitor-transitions — natürliche-sehende Seitenübergänge

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

Für Tailwind-Sicherheitsbereiche fügen Sie hinzu @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Siehe Verwendung von @capgo/capacitor-native-navigation, Verwendung von @capgo/capacitor-transitions, und das tailwind-capacitor-Repository für die spezifische Einrichtung von Next.js.

iOS-Layoutprobleme (Viewport, sichere Bereiche und horizontale Überschuss)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, ist das Hinzufügen von mehr oder das Anpassen der Viewport-Tags allein normalerweise nicht ausreichend. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird

App Router

exportieren Sie (app/von viewport Seiten-Router app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

setzen Sie den Viewport-Meta-Tag in (pages/für die spezifische Einrichtung von Next.js. pages/_app.tsx, nicht _document.tsx.

iOS-Sicherheitsbereich von einem Root-Wrapper nur behandeln

Erstelle eine einzelne App-Shell und füge dort Sicherheitsbereichs-Abstände an — nicht in mehreren verschachtelten Komponenten:

html,
body,
#__next {
  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);
}

Alle Seiteninhalte innerhalb von .app-shell. Doppelte Sicherheitsbereichs-Abstände in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

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

Setze Capacitor iOS-Sicherheitsbereich auf `contentInset` erst `never` erst

In bevorzugt native Einfügungen deaktivieren und lassen Sie CSS (oder Native Navigation’s capacitor.config.ts, lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css'Mischen Sie __CAPGO_KEEP_0__’s automatische Inhalts-Einfügung mit CSS

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das

, Tailwind 100vw, eine feste Pixelbreite oder eine große w-screenIn Safari Web Inspector, führen Sie aus: min-width.

Mit Tailwind ersetzen 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,
  }));

durch w-screen mit w-full wenn möglich. Viele horizontalen Überschussprobleme kommen von 100vw / w-screen, dupliziertem sicheren Bereichsabstand oder einem festschrittigen Container — nicht von der Viewport-Meta-Tags selbst.

Over-the-Air-Updates

Einrichten Capgo Um Updates ohne App-Store-Neuabstimmung zu pushen:

bunx @capgo/cli init

Fehlersuche

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“ Erstelle android/local.properties mit sdk.dir=/path/to/android/sdk

Änderungen erscheinen nicht auf dem Gerät Stelle sicher, dass du nach der Änderung bun run mobile nach der Änderung. Für Live-Reload überprüfe, ob die IP-Adresse korrekt ist und der Entwicklungs-Server läuft.

Ressourcen

Ist Ihr App bereit zum Versand? Erfahren Sie, wie Capgo Ihnen dabei hilft, Updates schneller zu liefern — sich für ein kostenloses Konto anmelden heute.

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

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

Erstelle eine Next.js-Mobilanwendung von Grund auf mit Capacitor 8