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

Einführung

Möchten Sie eine mobile App mit Next.js von Grund auf aufbauen? Diese Anleitung führt Sie durch die Erstellung eines brandneuen Next.js 15-Projekts, das von Anfang an für mobile Geräte konfiguriert ist, und verpackt es dann als native iOS- und Android-Apps 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
Statistische Exportkonfiguration für mobile Geräte
Capacitor 8 with essential plugins
Native iOS- und Android-Apps
Live-Reload-Entwicklungsumgebung

Bereits ein Next.js-App? Überprüfen Sie stattdessen Ihre Next.js-App auf Mobilgeräte umstellen 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 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 aus:

TypeScript: Ja (empfohlen)
ESLint: Ja
Tailwind CSS: Ja (empfohlen für die mobilen Stile)
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-Server zu benötigen
images: { unoptimized: true } — Deaktiviert die Next.js-Bildoptimierung (erfordert einen Server)
trailingSlash: true — Stellt sicher, dass die Routing-Funktion im 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 Build-Datei:

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-Kern-Pakete:

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 — Tastaturverhalten steuern
@capacitor/Splashbildschirm — Kontrolle des nativen Splashbildschirms
@capacitor/Statusleiste — Die Geräte-Statusleiste anpassen
@capacitor/Einstellungen — Schlüssel-Wert-Speicherung (wie localStorage, aber nativ)

Schritt 5: Capacitor initialisieren

Capacitor mit Ihren Projekt-Daten initialisieren:

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

Ersetzen Sie:

"My Mobile App" mit dem Namen Ihres Anwendungs-Displays
com.example.mymobileapp mit Ihrer 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: 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, die Dateien zu synchronisieren
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. Add to 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 live geladen.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirm

Erstellen wir eine einfache, mobilen-freundliche Startseite. 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 sichere Bereichsverwaltung hinzu

Smartphones haben Löcher, Heimindikatoren und Statusleisten. Fügen Sie die sichere Bereichsverwaltung 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 Einstellungen

App Icons: Standardicons durch neue ersetzen ios/App/App/Assets.xcassets und android/app/src/main/res
Splash Screen: In native Projekten anpassen oder @capacitor/splash-screen config
Deep Links: URL-Schemata für Ihre App konfigurieren

Mehr Funktionen hinzufügen

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

Native UI und Übergänge

Verwenden Sie anstatt Konsta UI Capgo-Plugins für einen nativen mobilen Look:

@capgo/capacitor-native-navigation — Liquid Glass-Tastenleiste 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ügen Sie für Tailwind-Safe-Areas 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 Next.js-spezifische Einrichtung.

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

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar erscheinen, hilft das Hinzufügen oder Ändern des Viewport-Tags normalerweise nicht. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird

App Router

export (app/von viewport Pages Router app/layout.tsx:

import type { Viewport } from 'next';

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

legen Sie den Viewport-Meta-Tag in (pages/protectedTokens pages/_app.tsxHandle iOS Safe Area aus einer einzigen Root-Wrapper _document.tsx.

Erstelle eine einzelne App-Shell und füge dort Safe-Area-Padding an — nicht in mehreren verschachtelten Komponenten:

Um alle Seite-Inhalte innerhalb

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

. Doppeltes Safe-Area-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die UI oft gekürzt oder zu groß aussehen. .app-shellMit

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorauf dieser einzigen Hülle ausdrücken. pt-safe pb-safe px-safe Setze __CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` context: Seite/Bereich: Produktseite mit Live-Updates. Rolle: Kurzer UI-Label oder Navigationselement. Nachrichtenschlüssel `live_update_dynamic_label_to` (Live Update Dynamic Label To). `never` erst

In capacitor.config.ts, bevorzugt native inset disabled und lasse CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Fläche besitzen:

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

Mischen Sie Capacitor’s automatische Inhaltseinstellung mit CSS env(safe-area-inset-*) padding ist eine häufige Ursache für doppelte Abstände.

Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine feste 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 durch w-full Wenn möglich. Viele horizontalen Überschussprobleme kommen von 100vw / w-screendoppeltem sicheren Bereichsabstand oder einem festschwellenen Container — nicht von der Viewport-Meta-Tags selbst.

Over-the-Air-Updates

Einstellungen Capgo um Updates ohne App-Store-Neuabmeldung zu pushen:

bunx @capgo/cli init

Hilfe bei Problemen

Builds scheitern mit „Cannot find module“ Ausführen bun install und probieren Sie es erneut.

iOS: „Kein Signierungszertifikat 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 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.

Ressourcen

Bereit, Ihre App zu verschicken? Lernen 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 bereits Build a Next.js Mobile App von Grund auf mit Capacitor 8 verwenden, 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 zur Produktionsablauf in Capgo Integrations CI/CD-Integration zur Implementierungsdetail in CI/CD-Integration, und GitHub Aktionen-Integration zur Implementierungsdetail in GitHub Aktionen-Integration.

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