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

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-Apps verpackt wird mit Capacitor 8.

Mit diesem Tutorial haben Sie am Ende 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.

Zeitbedarf: ~30 Minuten

Was Sie bauen werden:

• Ein neues Next.js 15-Projekt mit App Router
• Konfiguration für statische Exporte für Mobilgeräte
• Capacitor 8 mit wichtigen Plugins
• Nativ für iOS- und Android-Geräte
• Live-Reload-Entwicklungsumgebung

Haben Sie bereits eine Next.js-Anwendung? Überprüfen Sie stattdessen Convert Your Next.js App to Mobile anstatt.

Voraussetzungen

Stellen Sie sicher, dass Sie diese installiert haben:

• 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

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

Capacitor erfordert statische HTML/JS/CSS-Dateien. Konfigurieren Sie Next.js für statische Exportierung, indem Sie die folgenden Einstellungen aktualisieren: 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 erfordern
• 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 Capacitor-Kernpakete:

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 — Ereignisse im App-Lebenszyklus (Vordergrund/Hintergrund, tiefere Links)
• @capacitor/keyboard — Kontrolle des Splash-Screens
• @capacitor/splash-screen @__CAPGO_KEEP_0__/keyboard
• @capacitor/splash-screen — Die Gerätestatusleiste anpassen
• @capacitor/vorlieben — Schlüssel-Wert-Speicher (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 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 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

Installieren Sie die Plattform-Pakete:

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

Öffnen Sie in iOS-Simulator:

bun run mobile:ios

Oder Android-Emulator:

bun run mobile:android

In Xcode (iOS):

1. Wählen Sie einen Simulator aus dem Geräte-Auswahlfeld
2. Klicken Sie auf die Play-Taste oder drücken Sie Cmd + R

In Android Studio:

1. Warten Sie, bis Gradle fertig ist, sich zu synchronisieren
2. Wählen Sie ein Emulator aus dem Geräte-Auswahlfeld
3. Klicken Sie auf die Ausführungs-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.

1. Finden Sie Ihre lokale IP-Adresse:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. 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;

3. Starten Sie den Entwicklungs-Server und kopieren Sie die Konfiguration zu native:

bun run dev &
NODE_ENV=development bunx cap copy

4. 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 Bildschirm

Erstellen wir eine einfache, mobilen-freundliche Startseite. 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: Fügen Sie die sichere Bereichsverwaltung hinzu

Mobile Geräte haben Notcher, 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
└── ...

Zukünftige Schritte

Seite/ Bereich: Capgo Builder / native cloud build Produktseite. Rolle: Kurzer UI-Label oder Navigationselement. Nachrichten Schlüssel `native_build_builder_credit_next` (Native Build Builder Credit Next).

Sie haben jetzt eine funktionierende Next.js-Mobilanwendung. Hier ist, was Sie als Nächstes tun sollten:

• Wichtige Einstellungen App-Ikone: ios/App/App/Assets.xcassets Ersatz der Standard-Ikone in android/app/src/main/res
• und (und, siehe Seite trust.astro, Nachrichten Schlüssel `and` (And). Anpassen in native Projekten oder verwenden @capacitor/splash-screen Konfiguration
• Tiefe Links: Konfigurieren Sie die URL-Schemata für Ihre App

Hinzufügen von Funktionen

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

Verwenden Sie native UI und Übergänge

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

• @capgo/capacitor-native-Navigation --- Glasartige Tab-Leiste und native Navbar
• @capgo/capacitor-Übergänge --- Übergänge mit nativem Gefühl

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

Für sichere Bereiche von Tailwind, fügen Sie @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Siehe Verwendung von @capgo/capacitor-native-Navigation, Verwendung von @capgo/capacitor-Übergänge, und das tailwind-capacitor-Repo für die Next.js-spezifische Einrichtung.

Fehlerbehebung von iOS-Layout-Problemen (Viewport, sichere Bereiche und horizontale Überschuss)

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

Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird

App Router (app/): export} viewport von app/layout.tsx:

import type { Viewport } from 'next';

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

Pages Router (pages/): setzen Sie den Viewport-Meta-Tag in pages/_app.tsx, nicht _document.tsx.

Behandeln Sie die iOS-Sicherheitszone von einem einzigen Root-Wrapper aus

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

Umfasst alle Seite-Inhalte innerhalb .app-shell. Duplicated safe-area padding in headers, modals, und Layout-Wrapper macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitor, kannst du denselben Abstand mit Hilfsmitteln wie pt-safe pb-safe px-safe auf dieser einzelnen Hülle.

Setze Capacitor iOS contentInset auf never erst

In capacitor.config.ts, bevorzuge native Eingriff deaktiviert und lasse CSS (oder Native Navigation’s contentInsetMode: 'css') den sicheren Bereich besorgen:

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

Mische Capacitor’s automatische Inhalts-Einrückung mit CSS env(safe-area-inset-*) Die Padding ist eine häufige Ursache für doppelte Zeilenabstä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 wenn möglich. Viele horizontale Überlaufprobleme kommen von w-full , dupliziertem sicheren Bereich-Padding oder einem festsitzenden Container — nicht von der Viewport-Meta-Tags selbst. 100vw / w-screenÜber-der-Luft-Updates

Konfigurieren Sie

Set up Capgo Updates ohne App-Store-Neuveröffentlichung pushen:

bunx @capgo/cli init

Schwierigkeiten beim Auflösen

Build fehlt mit „Cannot find module“ Starten bun install und versuchen Sie es erneut.

iOS: „Kein Signaturidentität gefunden“ Öffnen Sie Xcode, gehen Sie zu Signieren & Fähigkeiten 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 gerannt haben bun run mobile nachdem Sie Änderungen vorgenommen haben. Für Live-Neustart überprüfen Sie, ob die IP-Adresse korrekt ist und der Entwicklungs-Server läuft.

Ressourcen

• Capacitor 8 Dokumentation
• Next.js 15 Dokumentation
• Capgo - Live-Updates
• @ capgo/ capacitor-native-Navigation
• @ capgo/ capacitor-Übergänge
• @ capgo/ tailwind-capacitor

Bereit, Ihre App zu verschicken? Lernen Sie, wie Capgo Ihnen dabei helfen kann, Updates schneller zu liefern — jetzt anmelden heute.

Fortsetzung 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_KEEP_0__ CI/CD Capgo CI/CD Capgo CI/CD für den Produktworkflow Capgo Native Builds Capgo Native Builds für den Produktworkflow Capgo Integrations for the product workflow in Capgo Integrations, CI/CD-Integration __CAPGO_KEEP_0__ Integrations für die Implementierungsdetails in CI/CD-Integration GitHub Aktionen Integration zur Implementierungsdetail in GitHub Aktionen Integration.