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

Einführung

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

Capacitor umhüllt Ihre Web-App in einem nativen Container, der Ihnen Zugriff auf Geräteeinrichtungen wie Kamera, Dateisystem und Push-Benachrichtigungen bietet, während Ihre bestehende React-Codebasis erhalten bleibt. Im Gegensatz zu React Native müssen Sie nichts umschreiben – Ihre Next.js code läuft unverändert weiter.

Was Sie lernen werden:

Konfigurieren Sie Ihre bestehende Next.js-Anwendung für statische Exportierung
Fügen Sie Capacitor 8 mit wichtigen nativen Plugins hinzu
Bauen und testen Sie auf iOS- und Android-Emulatoren
Aktivieren Sie Live-Reload für eine schnellere Entwicklung
Lösen Sie häufige iOS-Ansichtsprobleme (Ansichtsbereich, sichere Fläche, horizontale Überlauf)
Fügen Sie natürliche Anzeigen mit Capgo Native Navigation und Transitions hinzu

Planen Sie ein neues Projekt von Grund auf? Überprüfen Sie unsere Anleitung zu Building a Next.js Mobile App from Scratch.

Vorteile der Verwendung von Next.js und Capacitor

Code Wiederverwendbarkeit: Next.js ermöglicht es Ihnen, wiederholbare Komponenten zu schreiben und code zwischen Ihren Web- und Mobilanwendungen zu teilen, wodurch Entwicklungszeit und -bemühungen eingespart werden.
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 Server-Seiten-Rendering 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.
: __CAPGO_KEEP_0__ bietet Zugriff auf nativere Gerätefunktionen wie die Kamera, die Geolocation und vieles mehr, um Ihnen die Möglichkeit zu geben, feature-reiche Mobilanwendungen 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 __CAPGO_KEEP_0__ können Sie Ihre Mobilanwendung mit bekannten Webtechnologien entwickeln und testen, wodurch die Lernkurve reduziert und der Entwicklungsprozess gestreamt wird.

Voraussetzungen

: Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben: Node.js 18+
installiert sind (installiert sind ist a German translation of installed, the word is used in the context of the text, which is a list of prerequisites, and the translation is used to maintain the same tone and style as the original text.) Next.js 15+ Anwendung
Xcode (für iOS-Entwicklung, nur macOS)
Android Studio (für Android-Entwicklung)

Konfiguration Ihrer Next.js-Anwendung für Mobilgeräte

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)

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

module.exports = nextConfig;

Die output: 'export' Wenn Sie die Einstellung verwenden, erzwingt Next.js die Erstellung statischer HTML-Dateien, und images: { unoptimized: true } vermeidet die Optimierung von Bildern von Next.js, 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 mobile-spezifische 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 Ausgabe, indem Sie Folgendes ausführen:

bun run build

Sie sollten ein out Ordner am Wurzel des Projekts sehen. Dieser enthält alle statischen Dateien, die Capacitor in Ihre native App einbündeln wird.

Capacitor 8 in Ihrem Projekt hinzufügen

Um Ihre Next.js App in eine native mobile 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 werden:

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

Welche Plugins bieten wichtige Funktionen:

@capacitor/app: App-Lebenszyklusereignisse (Vordergrund/Hintergrund, URLs) verwalten
@capacitor/keyboard: Tastaturenverhalten auf Mobilgeräten steuern
@capacitor/splash-screen: Die native Splash-Screen verwalten
@capacitor/preferences: Schlüssel-Wert-Daten persistent speichern

Initialisieren Sie Capacitor mit Ihren Projekt-Daten:

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

Ersatz my-app mit Ihrem App-Namen und com.example.myapp mit Ihrer App-ID (Umkehrung der Domänennotation).

Erstellen oder aktualisieren Sie 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;

Installieren Sie native Plattformen:

bun add @capacitor/ios @capacitor/android

Fügen Sie die native Plattformordner:

bunx cap add ios
bunx cap add android

Capacitor wird die ios und android context

Seite/Area: Capgo-Marketing-Website. Rolle: Kurze UI-Schaltfläche oder Navigationspunkt. Gesehen in: Seite trust.astro. Nachrichtsschlüssel `und` (Und). Ordner am Root Ihres Projekts, die die native Projekte enthalten.Um das Android-Projekt zu bauen, benötigen Sie Android Studio.

Dein Projekt bauen und synchronisieren:

bun run mobile

Dies läuft deine benutzerdefinierte Skript aus, das das Next.js-Projekt baut und die statischen Dateien mit den nativen Plattformen synchronisiert.

Erstellung und Bereitstellung von nativen Apps

Um deine native mobile App zu erstellen und zu bereitstellen, folge bitte diesen Schritten: Um iOS-Apps zu entwickeln, musst du Xcode installiert haben, und für Android-Apps musst du Android Studio installiert haben. Darüber hinaus musst du, wenn du deine App im App Store verteilen möchtest, für iOS im Apple Developer Program und für Android im Google Play Console angemeldet sein. Öffne die native Projekte: Für iOS: Für Android: Oder direkt mit __CAPGO_KEEP_0__ __CAPGO_KEEP_1__:

Erstellung und Bereitstellung von nativen Apps

bun run mobile:ios

Öffne die native Projekte:

bun run mobile:android

Or directly with Capacitor CLI:

bunx cap open ios
bunx cap open android

Entwickeln 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 Schaltfläche "Ausführen", um die App auf einem verbundenen Gerät oder einem Emulator zu deployen.
In Xcode stellen Sie Ihr Signierungskonto ein, um die App auf einem echten Gerät zu deployen. Wenn Sie dies noch nicht getan haben, wird Xcode Ihnen 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 Schaltfläche "Spiel" zum Ausführen der App auf Ihrem verbundenen Gerät.

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 mobilen Gerät zu sehen. Um diese Funktion zu aktivieren, folgen Sie diesen Schritten:

Finden Sie Ihre lokale IP-Adresse:

Auf macOS führen Sie den folgenden Befehl in der Terminal-Anwendung aus:
```
ipconfig getifaddr en0
```
On Windows, führen Sie Folgendes aus:
```
ipconfig
```
Suchen Sie nach der IPv4-Adresse im Ausgabe.

Update Ihrer capacitor.config.ts zum Punkt Ihres Entwicklungsservers:

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;

Ersatz 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 Befehl kopiert das Web-Ordner und Konfigurationsänderungen in das native Projekt ohne Aktualisierung des gesamten Projekts.

Wiedergebaut und das App auf Ihrem Gerät mit Android Studio oder Xcode ausführen.

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

Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an nativen Dateien vornehmen, müssen Sie das native Projekt neu erstellen, da live-Neuladen nur auf Web code-Änderungen anwendbar ist.

Mit Capacitor-Plugins

Capacitor-Plugins ermöglichen Ihnen, Zugriff auf native Gerätefunktionen von Ihrem Next.js-Anwendungscode zu erhalten. Lassen Sie uns sehen, wie Sie das Teilen-Plugin als Beispiel verwenden:

Installieren Sie das Teilen-Plugin:

bun add @capacitor/share

Ändern Sie 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:

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

bun run mobile

Oder synchronisieren Sie ohne Neubereitstellung:

bunx cap sync

Rebuild und führen Sie die App auf Ihrem Gerät aus.

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 Ich habe Jahre lang mit Ionic gearbeite, um cross-plattformische Anwendungen zu erstellen, aber die Integration mit Next.js ist hackig und selten wertvoll, wenn du bereits.

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

hast. Für einen nativen Mobilgefühl in einer Next.js + capgo-Anwendung verwende stattdessen capacitor-Plugins anstelle von web-only UI-Kits wie Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
@capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

— Ionic-Style-Seiteneinblendungen und iOS-Rück-Edge-Swipe in der WebView-Schicht, ohne Ionic-Benutzeroberfläche zu übernehmen. Installiere beide:

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

Konfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit Webinhalte die native Balken respektieren:

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

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

Rendern Sie eine Liquid Glass-Tasteleiste (iOS verwendet die Systemeigene Rendering; Android verwendet einen verschwommenen 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 ein:

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

initTransitions({ platform: 'auto' });

Wrap routed Pages in cap-router-outlet, cap-page, und cap-content, und rufen Sie setDirection('forward') oder setDirection('back') vorher router.push() oder router.back(). Duplizieren Sie Web-Über- und Fußzeilen nicht, wenn native Navigation diese Oberflächen besitzt.

Siehe die vollständigen Anleitungen: Verwenden Sie @capgo/capacitor-native-navigation And Mit @capgo/capacitor-Übergängen.

Sichere Bereiche mit Tailwind

Für die sicheren Bereiche des Geräts in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (als) tailwind-capacitor auf npm veröffentlicht. Es bietet safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

, und styles/globals.css:

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

anstatt pt-safe, pb-safeanstatt, sie überall zu verteilen px-safe In env(safe-area-inset-*) per Hand. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Next.js-Einrichtung fehlt, Öffnen Sie einen PR auf GitHub.

Fixierung von iOS-Layoutproblemen (Viewport, sichere Fläche und horizontale Überschuss)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar sind, hilft das Hinzufügen oder Anpassen 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/, nicht pages/_app.tsxApp Router export von Pages Router legen Sie den Viewport-Meta-Tag in , nicht _document.tsx ( _document.tsx Die Anwendung von (Next.js) kann die Tags für die Ansichtsverhalten nicht wie erwartet anwenden.)

Behandeln Sie das iOS-Sicherheitsbereich von einem einzigen Root-Wrapper aus

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort den Sicherheitsbereich-Puffer an – 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-shellDie duplizierte Sicherheitsbereich-Pufferung in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

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

Setzen Sie Capacitor iOS `contentInset` auf " `never` erste

In capacitor.config.ts, bevor Sie native Einstellungen deaktivieren und lassen Sie 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 Inhalts-Einstellung mit CSS env(safe-area-inset-*) 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,
  }));

Ersetzen Sie mit Tailwind w-screen mit w-full wenn möglich. Viele horizontalen Überschreitungsprobleme kommen von 100vw / w-screendoppeltem sicheren Bereichsabstand oder einem festsitzenden Container — nicht von der Viewport-Meta-Tags selbst.

Leistungsoptimierung

Um die beste Leistung Ihres Next.js- und Capacitor-Apps sicherzustellen, beachten Sie die folgenden Best Practices:

Klein halten Sie die App-Größe, indem Sie unnötige Abhängigkeiten und Assets entfernen.
Optimieren Sie Bilder und andere Medien-Dateien, um die Ladezeiten zu reduzieren.
Implementieren Sie die lazy Loading für Komponenten und Seiten, um die Initial-Ladeleistung zu verbessern.
Verwenden Sie die Server-Seiten-Rendern (SSR) mit Next.js, um die Ladezeit und die Suchmaschinenoptimierung (SEO) des Apps zu verbessern.
Nutzen Sie die Capacitor-integrierten Optimierungen, wie z.B. die Web-View-Caching und die App-Bündelung.

Zusammenfassung

Ihr Next.js-Web-Anwendungscode wurde erfolgreich in native iOS- und Android-Apps umgewandelt, die mit Capacitor 8 ausgeführt werden. Ihr Web-Codebase läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräte-APIs.

Was Sie erreicht haben:

Next.js für statische Exporte konfiguriert
Capacitor 8 mit wichtigen Plugins hinzugefügt
Für iOS- und Android-Emulatoren erstellt und bereitgestellt
Lebendes Reload für die Entwicklung aktiviert
Gemeinsame iOS-Layoutprobleme (viewport, sichere Fläche, Überfluss) gelöst
Einen natürlichen Anblick mit Capgo Native Navigation und Transitions hinzugefügt

Nächste Schritte:

Einrichten Capgo für über das Internet erfolgende Updates ohne Wiederabgabe im App-Store
Mehr native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzufügen
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

Neuanfang? Überprüfen Sie Erstellen Sie eine native mobile App mit Next.js und Capacitor von Grund auf um eine Schritt-für-Schritt-Anleitung zu erhalten.

Ressourcen

Next.js-Dokumentation
@capgo/capacitor-native-navigation — Liquid Glass-Tastenleiste und native Chrome
Capacitor 8-Dokumentation
@capgo/capacitor-transitions — native anfühlfende Seitenübergänge
@capgo/tailwind-capacitor — Tailwind-sichere-Bereichs-Utilities für Capacitor
Capgo - Live-Updates für Capacitor-Apps

Lernen Sie, wie Capgo Ihnen helfen kann, bessere Apps schneller zu bauen Melden Sie sich für ein kostenloses Konto an heute.

Fahren Sie mit Convert Your Next.js App zu iOS & Android mit Capacitor 8 fort

Wenn Sie __CAPGO_KEEP_0__ 8 verwenden Um native Plugin-Arbeit zu planen, verbinden Sie es mit Capacitor Plugin-Verzeichnis für den Produktworkflow in __CAPGO_KEEP_0__ Plugin-Verzeichnis Capgo for the product workflow in Capgo Plugin Directory, Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetail in Hinzufügen oder Aktualisieren von Plugins Ionische Unternehmens-Plugin-Alternativen zum Produktworkflow in Ionische Unternehmens-Plugin-Alternativen, und Capgo Native Builds zum Produktworkflow in Capgo Native Builds.

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