Ihre Next.js-App auf iOS und Android mit Capacitor 8 umwandeln

Einleitung

Haben Sie bereits eine Next.js-Webanwendung? In diesem Leitfaden erfahren Sie, wie Sie sie in native iOS- und Android-Mobilanwendungen umwandeln können, indem Sie Capacitor 8 — die neueste Version mit verbessertem Leistung und neuen Funktionen.

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing React codebase. Unlike React Native, you don’t need to rewrite anything — your Next.js code runs as-is.

Ihre Webanwendung in eine native Container umschließt, wodurch Sie Zugriff auf Geräte-APIs wie Kamera, Dateisystem und Push-Benachrichtigungen erhalten, während Ihre bestehende React-Codebasis erhalten bleibt. Im Gegensatz zu React Native müssen Sie nichts umschreiben — Ihre Next.js-Anwendung läuft unverändert.

Wat werden Sie lernen:
Add Capacitor 8 with essential native plugins
Hinzufügen Sie Capacitor 8 mit wichtigen native Plugins
Erstellen und testen Sie auf iOS- und Android-Emulatoren
Aktivieren Sie Live-Reload für eine schnellere Entwicklung
Add native-feeling UI with Capgo Native Navigation and Transitions

Interessiert an einem neuen Projekt von Grund auf? Erstellung einer mobilen Next.js-Anwendung von Grund auf.

Benefits of Using Next.js and Capacitor

Code Reusability: Next.js ermöglicht Ihnen, wiederholbar zu schreiben Komponenten und code zwischen Ihrer Web- und mobilen App zu teilen, was Entwicklungzeit und -bemühungen einspart.
Leistung: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
: Next.js bietet integrierte Leistungsoptimierungen, wie z.B. Server-Seiten-Rendern und __CAPGO_KEEP_0__-Splitting, um schnelle Ladezeiten und eine glatte Benutzererfahrung sicherzustellen.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
: Capacitor bietet Zugriff auf native Gerätefunktionen wie Kamera, Geolocation und mehr, um eine reichhaltige mobile App zu erstellen.: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

: Mit Capacitor können Sie Ihre mobile App mit bekannten Web-Technologien entwickeln und testen, was die Lernkurve reduziert und den Entwicklungsprozess vereinfacht.

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

Node.js 18+ installiert
Ein bestehendes Next.js 15+ Anwendung
Xcode (für iOS-Entwicklung, nur macOS)
Android Studio (für Android-Entwicklung)

Ihre Next.js-Anwendung für Mobilgeräte konfigurieren

Der erste Schritt besteht darin, Ihre Next.js-Anwendung für die statische Exportierung zu konfigurieren. Capacitor benötigt statische HTML/JS/CSS-Dateien, um sie in die native App zu packen.

Öffnen Sie Ihr next.config.js (oder next.config.ts) Datei und fügen Sie die Export-Konfiguration hinzu:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

Die output: 'export' Einstellung erzwingt Next.js, statische HTML-Dateien zu generieren, und images: { unoptimized: true } bypasses Next.js-Bildoptimierung, die einen Server erfordert.

Wichtig: If you’re using features that require a server (API routes, server components with data fetching, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Fügen Sie mobilespezifische Skripte zu Ihrem package.json:

{
  "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 statische Exportierung, indem Sie Folgendes ausführen:

bun run build

Sollten Sie ein out folder at the root of your project. This contains all the static files that Capacitor will bundle into your native app.

Hinzufügen von Capacitor 8 zu Ihrem Projekt

Um Ihre Next.js-Anwendung in einen nativen mobilen Container zu packen, folgen Sie diesen Schritten:

Installieren Sie Capacitor-Core und CLI:

bun add @capacitor/core
bun add -D @capacitor/cli

Installieren Sie die gängigen Capacitor-Plugins, die Sie benötigen:

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences

Diese Plugins liefern wichtige Funktionen:

@capacitor/app: Verwalten Sie Ereignisse im App-Lebenzyklus (Vordergrund/Hintergrund, URLs)
@capacitor/keyboard: Kontrollieren Sie die Tastaturverhalten auf dem Mobilgerät
@capacitor/splash-screen: Verwalten Sie die native Splash-Screen
@capacitor/preferences: Daten persistent speichern

Initialisiere Capacitor mit deinen Projekt-Daten:

bunx cap init my-app com.example.myapp --web-dir out

Ersetzen my-app mit deinem App-Namen und com.example.myapp mit deiner App-ID (umgekehrte Domänennotation).

Erstelle oder aktualisiere das capacitor.config.ts Datei mit der richtigen Konfiguration:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true,
    },
  },
};

export default config;

Installiere native Plattformen:

bun add @capacitor/ios @capacitor/android

Füge die native Plattform-Ordner hinzu:

bunx cap add ios
bunx cap add android

Capacitor wird ios und android Ordner am Root deines Projekts erstellen, die die native Projekte enthalten.

Um das Android-Projekt zu erstellen, benötigen Sie Android Studio. Für iOS benötigen Sie einen Mac mit Xcode.

Das Projekt bauen und synchronisieren:

bun run mobile

Dies führt Ihren benutzerdefinierten Skript aus, das das Next.js-Projekt erstellt und die statischen Dateien mit den nativen Plattformen synchronisiert.

Erstellung und Bereitstellung von nativen Apps

Um Ihre native mobile App zu erstellen und zu bereitstellen, folgen Sie bitte diesen Schritten: Um iOS-Apps zu entwickeln, benötigen Sie Xcode installiert, und für Android-Apps benötigen Sie Android Studio installiert. Darüber hinaus benötigen Sie, wenn Sie Ihre App im App Store verteilen möchten, sich für iOS im Apple Developer Programm und für Android im Google Play Console anzumelden.

Öffnen Sie die native Projekte:

Für iOS:

bun run mobile:ios

Für Android:

bun run mobile:android

Oder direkt mit Capacitor CLI:

bunx cap open ios
bunx cap open android

Bauen und ausführen Sie die App:

android-studio-run

In Android Studio warten Sie, bis das Projekt bereit ist, und klicken Sie dann auf die "Ausführen"-Schaltfläche, um die App auf einem verbundenen Gerät oder Emulator zu deployen.
In Xcode stellen Sie Ihr Signierkonto ein, um die App auf einem realen Gerät zu deployen. Wenn Sie dies noch nicht getan haben, wird Xcode Sie durch den Prozess führen (beachten Sie, dass Sie sich im Apple Developer Programm anmelden müssen). Sobald Sie eingerichtet sind, klicken Sie auf die "Play"-Schaltfläche, um die App auf Ihrem verbundenen Gerät auszuführen.

Glückwunsch! Sie haben erfolgreich Ihre Next.js-Web-App auf einem mobilen Gerät deployt.

Aber warten Sie, es gibt auch eine schnellere Möglichkeit, dies während der Entwicklung zu tun...

Capacitor Live Reload

Während der Entwicklung können Sie von Live Reloaden profitieren, um Änderungen sofort auf Ihrem Mobilgerät zu sehen. Um diese Funktion zu aktivieren, folgen Sie diesen Schritten:

Finden Sie Ihre lokale IP-Adresse:

Bei macOS führen Sie folgenden Befehl im Terminal aus:
```
ipconfig getifaddr en0
```
Bei Windows führen Sie:
```
ipconfig
```
Suchen Sie nach der IPv4-Adresse in der Ausgabe.

Passen Sie Ihre capacitor.config.ts zur Ihren Entwicklungsserver zuweisen:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
};

export default config;

Ersetzen Sie YOUR_IP_ADDRESS mit Ihrer lokalen IP-Adresse (z.B. 192.168.1.100).

Anwenden Sie die Änderungen an Ihrem nativen Projekt:

bunx cap copy

Die copy Kommando kopiert das Web-Ordner und Konfigurationsänderungen in das native Projekt ohne das gesamte Projekt zu aktualisieren.

Rebuild und fahren Sie das App auf Ihrem Gerät mit Android Studio oder Xcode.

Jetzt werden alle Änderungen an Ihrer Next.js App automatisch neu geladen, um diese Änderungen widerzuspiegeln.

Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an native Dateien vornehmen, müssen Sie das native Projekt neu erstellen, da live-aktuelle Neuaufladung nur auf Web code-Änderungen angewendet wird.

Verwendung von Capacitor-Plugins

Capacitor-Plugins ermöglichen Ihnen, native Gerätefunktionen von Ihrer Next.js App aus zu nutzen. Lassen Sie uns sehen, wie man das Teilen-Plugin als Beispiel verwendet:

Installieren Sie das Teilen-Plugin:

bun add @capacitor/share

Update das pages/index.js Datei, um das Teilen-Plugin zu verwenden:

import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';

export default function Home() {
  const share = async () => {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends',
    });
  };

  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href="https://nextjs.org">Capgo!</a>
        </h1>

        <p className={styles.description}>
          <h2>Cool channel</h2>
          <button onClick={() => share()}>Share now!</button>
        </p>
      </main>
    </div>
  );
}

Synchronisieren Sie die Änderungen mit dem native Projekt:

As erwähnt, müssen wir bei der Installation neuer Plugins eine Synchronisierung durchführen und die App dann auf unserem Gerät neu bereitstellen. Um dies zu tun, führen Sie bitte folgenden Befehl aus:

bun run mobile

Oder synchronisieren Sie einfach ohne Neuberechnung:

bunx cap sync

Die App auf Ihrem Gerät neu bereitstellen.

Jetzt, wenn Sie auf den Button „Jetzt teilen!“ klicken, erscheint das native Teilen-Dialogfeld, sodass Sie den Inhalt mit anderen Apps teilen können.

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas. ## Native-feeling UI with Capgo Native Navigation and Transitions

## Eine natürliche Benutzeroberfläche mit __CAPGO_KEEP_1__-Native-Navigation und -Übergängen Im Laufe der Jahre habe ich bereits mit Ionic gearbeite, um cross-plattformische Anwendungen zu erstellen, aber die Integration mit Next.js ist hackig und selten wertvoll, wenn Sie bereits .

For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

verwenden. Für einen natürlichen mobilen Look in einer Next.js + capgo-Anwendung verwenden Sie stattdessen capacitor-Plugins anstelle von web-only UI-Kits wie Konsta UI: @capgo/capacitor-native-navigation --- native Navbar, Liquid Glass Tabbar auf iOS und eine getönte Tabbar-Style auf Android. Ihr Next.js-Router hält die Routen-Zustände; der Plugin besitzt die native Chrome.
@capgo/capacitor-Übergänge --- Ionic-Style-Seiten-Übergänge und iOS-Rück-Edge-Swipe in der WebView-Schicht, ohne Ionic-UI zu übernehmen.

Install beide:

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

Konfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit Web-Inhalt die native Balken respektiert:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendern Sie eine getönte Liquid Glass Tabbar (iOS verwendet die Systemeigene Rendering; Android verwendet einen getönten WebView-Hintergrund):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

Fügen Sie native Seiten-Übergänge in Ihrem App-Shell hinzu:

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

Wrap routed Pages in cap-router-outlet, cap-pageund cap-contentund rufen Sie setDirection('forward') oder setDirection('back') vorher router.push() oder router.back()Vermeide Duplikate von Web-Überschriften oder -Fußern, wenn native Navigation diese Oberflächen besitzt.

Siehe die vollständigen Anleitungen: Verwenden Sie @capgo/capacitor-native-Navigation und Verwenden Sie @capgo/capacitor-Übergänge.

Sichere Bereiche mit Tailwind

Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (als tailwind-capacitor veröffentlicht auf npm). Es bietet safe-areas Utility-Funktionen und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

In styles/globals.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Verwenden Sie pt-safe, pb-safez.B. px-safe und env(safe-area-inset-*) anstatt sie manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Next.js-Konfiguration fehlt, open a PR on GitHub.

Fixing iOS Layout Issues (Viewport, Safe Area, und Horizontal Overflow)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder passen Sie die Viewport-Tags alleine an, ist es normalerweise nicht ausreichend. Arbeiten Sie durch diese Checks in der Reihenfolge.

Stellen Sie sicher, dass die Viewport-Metatag 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',
};

Seiten-Router (pages/): Setzen Sie die Viewport-Metatag ein pages/_app.tsx, nicht _document.tsx (Next.js kann die Tags für die Viewport-Verhaltensweise nicht wie erwartet anwenden). _document.tsx Behandeln Sie das iOS-Sicherheitsbereich von einem einzigen Root-Wrapper aus

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort den Sicherheitsbereich-Padding hinzu — nicht in mehreren verschachtelten Komponenten:

Verwenden Sie alle Seiteninhalte innerhalb von

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

Doppelte Sicherheitsbereich-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aus. .app-shellMit

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor, Sie können denselben Abstand auch mit Hilfsmitteln wie pt-safe pb-safe px-safe auf dieser einzelnen Shell.

Setzen Sie Capacitor iOS `contentInset` zu `never` erst

auf capacitor.config.ts, bevorzugen Sie native inset disabled und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') den sicheren Bereich besetzen:

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

Mischen Sie Capacitor’s automatische Inhaltsabstand mit CSS env(safe-area-inset-*) ist eine häufige Ursache für doppelten Abstand.

Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das 100vwTailwind w-screen, eine feste Pixelbreite oder eine große min-width.

In Safari Web Inspector, ausführen:

[...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 w-screen mit w-full wenn möglich. Viele horizontale Überlaufprobleme kommen von 100vw / w-screen, dupliziertem sicheren Bereichsabstand oder einer feste-Breiten-Container — nicht von der Viewport-Meta-Tags selbst.

Leistungsoptimierung

To ensure optimal performance of your Next.js and Capacitor app, consider the following best practices:

Minimieren Sie die App-Größe, indem Sie nicht benötigte Abhängigkeiten und Assets entfernen.
Optimieren Sie Bilder und andere Medien-Dateien, um die Ladezeiten zu reduzieren.
Implementieren Sie lazy Loading für Komponenten und Seiten, um die Initial-Lade-Leistung zu verbessern.
Verwenden Sie die Serverseitige Rendern (SSR) mit Next.js, um die Ladezeit und die Suchmaschinenoptimierung (SEO) der App zu verbessern.
Nutzen Sie die integrierten Optimierungen von Capacitor, wie z.B. das Caching des Web-Views und das App-Bündeln.

Zusammenfassung

Sie haben erfolgreich Ihre bestehende Next.js-Webanwendung in native iOS- und Android-Apps umgewandelt, indem Sie Capacitor 8 einsetzten. Ihre Web-Codebasis läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräteeinblendungen.

Wat haben Sie erreicht:

Konfiguriert Next.js für statische Exportierung
Fügte Capacitor 8 mit wichtigen Plugins hinzu
Baut und deployt auf iOS- und Android-Simulatoren
Aktiviert Live-Reload für die Entwicklung
Löste häufige iOS-Ansichtsprobleme (viewport, safe area, overflow) aus
Fügte eine native anfühlsende UI mit Capgo Native Navigation und Transitions hinzu

Zukünftige Schritte: (Nächste Schritte)

Einrichten Capgo Für über das Internet verfügbare Updates ohne Wiederabgabe bei der App-Stores
Hinzufügen von mehr nativen Plugins wie Kamera, Standort oder Push-Benachrichtigungen
Konfigurieren Sie App-Ikonen und Splash-Screens für die Produktion
Vorbereiten Sie Ihre App für die Einreichung bei App Store und Google Play

Starten Sie ein neues Projekt? Überprüfen Sie Ein Next.js-Mobil-App von Grund auf aufbauen zur Anleitung.

Ressourcen

Next.js-Dokumentation
@capgo/capacitor-native-Navigation --- Glasartige Liquid Tab-Leiste und nativer Chrome-Browser
Capacitor 8 Dokumentation
@capgo/capacitor-Übergänge --- Übergänge, die wie native Seiten fühlen
@capgo/tailwind-capacitor --- Tailwind-Sicherheitsbereiche für Capacitor
Capgo - Live-Updates für Capacitor-Apps

Erhalten Sie Informationen, wie Capgo Ihnen helfen kann, bessere Apps schneller zu erstellen. Registrieren Sie sich für ein kostenloses Konto heute.

Fortsetzen Sie mit Konvertieren Sie Ihre Next.js-App in iOS- und Android-Apps mit Capacitor 8

Wenn Sie __CAPGO_KEEP_0__ verwenden Convert Your Next.js App to iOS & Android with Capacitor 8 um native Plugin-Arbeit zu planen, verbinden Sie es mit Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins Ionic Enterprise Plugin Alternativen für den Produktworkflow in Ionic Enterprise Plugin Alternativen, und Capgo Native Builds für den Produktworkflow in Capgo Native Builds

Konvertieren Sie Ihre Next.js-Anwendung in iOS- und Android-Anwendungen mit Capacitor 8