Erstelle eine 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 einer brandneuen Next.js 15-Projekt, 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.

Nach Abschluss 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:

• 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 besitzen? 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

Wählen Sie bei der Aufforderung diese Optionen:

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

Capacitor erfordert statische HTML/JS/CSS-Dateien. Konfiguriere Next.js für statische Exporte, 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 Routingfunktion in der nativen WebView ordnungsgemäß funktioniert

Schritt 3: Füge mobile Skripte hinzu

Aktualisieren Sie Ihre package.json mit Skripten für mobile Entwicklung:

{
  "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 Kern-Pakete von Capacitor:

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 — Schlüssel-Wert-Speicher (wie localStorage, aber native)
• Schritt 5: Initialisierung von capacitor Initialisiere __CAPGO_KEEP_0__ mit deinen Projekt-Daten:

Step 5: Initialize Capacitor

Initialize Capacitor with your project details:

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

mit der App-ID (umgekehrte Domänennotation)

• "My Mobile App" — Kontrolle der Tastaturenbetonsteuerung
• com.example.mymobileapp @__CAPGO_KEEP_0__/status-bar

Dies erstellt capacitor.config.tsUpdate 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):

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

In Android Studio:

1. Warten Sie, bis Gradle fertig ist, die Daten zu synchronisieren
2. Wählen Sie einen Emulator aus der Geräte-Auswahlliste
3. 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.

1. Finden Sie Ihre lokale IP-Adresse:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

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

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

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 live geladen.

Schritt 9: Erstellen Sie Ihre erste mobile Bildschirmanzeige

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 eine sichere Bereichsverwaltung hinzu

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

Sie haben jetzt eine funktionierende Next.js-Mobilanwendung. Hier sind die nächsten Schritte:

Wichtige Einstellungen

• App Icons: Standardicons durch neue ersetzen in ios/App/App/Assets.xcassets und android/app/src/main/res
• Splash Screen: In nativen 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
• Standort: 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-Tasteleiste und nativer Navbar
• @capgo/capacitor-Übergänge — natürliche-sehende Seitenübergänge

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

Für Tailwind-Safe-Areas fügen Sie hinzu: @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-Repository für die spezifische Einrichtung von Next.js.

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

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar sind, 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 die Viewport-Metatag 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-Metatag in (pages/protectedTokens pages/_app.tsx, nicht _document.tsx.

iOS-Sicherheitsbereich nur von einer Root-Wrapper aus handhaben

Erstellen Sie eine einzelne App-Shell und fügen Sie dort Sicherheitsbereich-Puffer zu — 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-shellViele Duplikate von Sicherheitsbereich-Puffer in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitor können Sie denselben Puffer mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Schale ausdrücken.

Setzen Sie Capacitor iOS contentInset erst never zuerst

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

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

Mischen Sie Capacitor’s automatische Inhalts-Einrückung 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 Pixel-Breite 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 horizontale Überschreitung von Problemen kommen von 100vw / w-screen, dupliziertes sicheres Bereich Puffer, oder ein fester Breite Container — nicht von der Viewport Meta-Tag selbst.

Über-die-Luft-Updates

Einrichten Capgo um Updates ohne App-Store-Resubmission zu pushen:

bunx @capgo/cli init

Fehlersuche

Builds scheitern mit „Cannot find module“ Ausführen 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.

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-Neuladen, ü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 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 zur Planung der CI/CD-Automatisierung verwenden, 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.