Next.js Mobile App von vorne bis hinten mit Capacitor 8 erstellen

Einführung

Wollen Sie eine mobile App mit Next.js von Grund auf erstellen? 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 mit Capacitor 8.

Durch diese Anleitung erhalten Sie eine funktionierende mobile App, 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:

Eine neue Next.js 15-Projekt mit App Router
Statistische Exportkonfiguration für mobile Geräte
Capacitor 8 mit wichtigen Plugins
Nativ-Apps für iOS und Android
Live-Reload-Entwicklungsumgebung

Bereits ein Next.js-Projekt? Schauen Sie sich an Ihre Next.js-Anwendung auf Mobilgeräte umwandeln anstatt.

Voraussetzungen

Stellen Sie sicher, dass diese installiert sind:

Node.js 18+ (überprüfen Sie mit node --version)
Bun Package-Manager (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

Erstellen Sie zunächst ein frisches Next.js 15-Projekt:

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

Wenn gefragt, diese Optionen auswählen.

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

Zu Ihrem Projekt navigieren:

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;

Wozu diese Einstellungen?

output: 'export' — Erzeugt statisches HTML anstatt eines Node.js-Servers zu erfordern
images: { unoptimized: true } — Deaktiviert Next.js Bildoptimierung (erfordert einen Server)
trailingSlash: true — Stellt die richtige Routensteuerung im nativen WebView sicher

Schritt 3: Hinzufügen von mobilen Skripten

Aktualisieren Sie 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 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 — App-Laufzeitereignisse (Vordergrund/Hintergrund, tiefere Links)
@capacitor/keyboard — Tastaturverhalten steuern
@capacitor/Splashbildschirm — Kontrolle der nativen Splash-Screen
@capacitor/status-bar — Geräte-Status-Leiste anpassen
@capacitor/preferences — Schlüssel-Wert-Speicherung (wie localStorage, aber native)

Schritt 5: Capacitor initialisieren

Initialize Capacitor with your project details:

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

Ersetzen Sie:

"My Mobile App" mit Ihrem Anwendungsbezeichner
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: 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: Erstellen und Ausführen

Deine Projekt erstellen und synchronisieren mit nativen 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 einen Simulator aus dem Geräte-Menü
Klicken Sie auf die Play-Taste oder drücken Sie Cmd + R

In Android Studio:

Warten auf Gradle, bis es sich synchronisiert hat
Wählen Sie ein Emulator-Gerät aus dem Geräte-Menü
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.

Finde deine lokale IP-Adresse:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Erstelle eine Entwicklungskonfiguration Capacitor. Füge hinzu: 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;

Starte den Dev-Server und kopiere Konfiguration nach native:

bun run dev &
NODE_ENV=development bunx cap copy

Rebuild in Xcode/Android Studio

Jetzt werden Änderungen an deinem Next.js code auf dem Gerät mit Hot-Reload aktualisiert.

Schritt 9: Erstelle deine erste mobile Bildschirmseite

Schritt 10: Füge sicheren Bereichs-Handling hinzu 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: Safe Area-Handling hinzufügen

Mobile Geräte haben Notch, Home-Indikatoren und Statusleisten. Fügen Sie die Verarbeitung von sicheren Bereichen mit Tailwind hinzu.

Update 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

Schritt 9: Erstelle deine erste mobile Bildschirmseite

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-Ikone: Ersatz der Standard-Ikone in ios/App/App/Assets.xcassets und android/app/src/main/res
Willkommensbildschirm: Anpassen in native Projekten oder verwenden @capacitor/splash-screen Konfiguration
Tiefenlinks: Konfigurieren Sie die URL-Schemata für Ihre App

Hinzufügen von weiteren Funktionen

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

Verwende stattdessen Capgo-Plugins anstelle von Konsta UI für einen nativen mobilen Look:

@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ügen Sie für Tailwind-Safe-Areas hinzu: @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Sehen Mit @capgo/capacitor-native-Navigation, Mit @capgo/capacitor-Übergänge, und das tailwind-capacitor-Repo zur spezifischen Einrichtung von Next.js.

iOS-Bereichsprobleme beheben (Viewport, sichere Fläche und horizontale Überschreitung)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder das Anpassen der Viewport-Tags alleine hilft normalerweise nicht. Arbeiten Sie durch diese Kontrollen in der Reihenfolge.

Stellen Sie sicher, dass die Viewport-Meta-Tags korrekt angewendet werden.

): export (app/): export viewport von app/layout.tsx:

import type { Viewport } from 'next';

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

Seitenrouter (pages/): fügen Sie die Viewport-Metatag ein pages/_app.tsxnicht _document.tsx.

Verwenden Sie den iOS-Safe Area nur von einem Root-Wrapper aus.

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort Sicherheitsbereich-Padding hinzu — 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);
}

Umgeben Sie alle Seiteninhalte mit .app-shellDoppelte Sicherheitsbereich-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitorkönnen Sie denselben Padding mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf diesem einzelnen Shell ausdrücken.

Set Capacitor iOS `contentInset` bis `never` erst

In capacitor.config.ts, bevor Sie native Einstellungen deaktivieren und CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Bereichsgröße übernehmen lässt:

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

Ersetzen Sie mit Tailwind, wenn möglich. w-screen mit w-full wenn möglich. Viele horizontale Überschreitungsausgaben kommen von 100vw / w-screen, duplizierte sichere Bereichsabstand oder ein fester Breitencontainer — nicht vom viewport-Meta-Tag selbst.

Konfigurieren Sie

Einrichten Capgo ohne App-Store-Neuveröffentlichung Updates bereitstellen:

bunx @capgo/cli init

Troubleshooting

Der Build schlägt fehl mit „Cannot find module“ Run 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 Entwicklerteam aus.

Android: „SDK-Ort nicht gefunden“ Erstellen android/local.properties mit sdk.dir=/path/to/android/sdk

Änderungen nicht auf Gerät sichtbar Stellen Sie sicher, dass Sie bun run mobile nachgemacht 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? Erfahren Sie, wie Capgo Ihnen dabei hilft, Updates schneller zu liefern — Registrieren Sie sich für ein kostenloses Konto heute.

Fortsetzen 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 zur Planung der CI/CD-Automatisierung, mit ihr verbinden Capgo CI/CD für den Produktworkflow in Capgo CI/CD Capgo nativee 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 und GitHub Actions-Integration für die Implementierungsdetails in GitHub Actions-Integration

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

Einführung

Voraussetzungen

Schritt 1: Erstellen Sie ein neues Next.js-Projekt

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

Schritt 3: Hinzufügen von mobilen Skripten

Schritt 4: Installieren Sie Capacitor 8

Schritt 5: Capacitor initialisieren

Schritt 6: Hinzufügen von Native Plattformen

Schritt 7: Erstellen und Ausführen

Schritt 8: Live Reload einrichten

Schritt 9: Erstelle deine erste mobile Bildschirmseite

Schritt 10: Safe Area-Handling hinzufügen

Projektstruktur

Nächste Schritte

Wichtige Einstellungen

Hinzufügen von weiteren Funktionen

Native UI und Übergänge

iOS-Bereichsprobleme beheben (Viewport, sichere Fläche und horizontale Überschreitung)

Stellen Sie sicher, dass die Viewport-Meta-Tags korrekt angewendet werden.

Verwenden Sie den iOS-Safe Area nur von einem Root-Wrapper aus.

Set Capacitor iOS contentInset bis never erst

Finden Sie das überlaufende Element

Konfigurieren Sie

Troubleshooting

Ressourcen

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

Set Capacitor iOS `contentInset` bis `never` erst