Next.js App mit Capacitor 8 zu iOS & Android konvertieren

Einführung

Have an existing Next.js web application? In this guide, you’ll learn how to transform it into native iOS and Android mobile apps using Capacitor 8 — die neueste Version mit verbesserter Performance und neuen Features.

Capacitor hüllt deine Web-App in einen nativen Container ein. So erhältst du Zugriff auf Device-APIs wie Kamera, Filesystem und Push-Notifications, während dein bestehender React-Code erhalten bleibt. Im Gegensatz zu React Native musst du nichts umschreiben – dein Next.js code läuft einfach so, wie er ist.

Das lernst du:

Konfiguration deiner Next.js App für den Static Export
Hinzufügen von Capacitor 8 mit essenziellen nativen Plugins
Build und Test auf iOS- und Android-Simulatoren
Live Reload für schnelleres Development aktivieren
Häufige iOS-Layout-Probleme lösen (Viewport, Safe Area, Horizontal Overflow)
Native UI mit Capgo Native Navigation und Transitions hinzufügen

Möchtest du ein neues Projekt von Grund auf starten? Schau dir unseren Guide an zu: Eine Next.js Mobile App von Grund auf bauen.

Vorteile von Next.js und Capacitor

Code Wiederverwendbarkeit: Mit Next.js kannst du wiederverwendbare Komponenten schreiben und code zwischen deinen Web- und Mobile-Apps teilen, was Zeit und Aufwand bei der Entwicklung spart.
Performance: Next.js bietet integrierte Performance-Optimierungen wie Server-Side Rendering und code Splitting, um schnelle Ladezeiten und eine reibungslose User Experience zu gewährleisten.
Native Funktionen: Capacitor bietet Zugriff auf native Gerätefunktionen wie Kamera, Geolocation und mehr, sodass du featurereiche Mobile-Apps bauen kannst.
Einfachere Entwicklung: Mit Capacitor kannst du deine Mobile-App mit vertrauten Web-Technologien entwickeln und testen, was die Lernkurve senkt und den Entwicklungsprozess optimiert.

Voraussetzungen

Before you begin, make sure you have:

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

Next.js App für Mobile konfigurieren

Zuerst musst du deine Next.js App für den Static Export konfigurieren. Capacitor benötigt statische HTML/JS/CSS-Dateien, um sie in die Native Build einzubinden.

Öffne deine next.config.js (oder next.config.ts) Datei und füge die Export-Konfiguration hinzu:

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

module.exports = nextConfig;

Der output: 'export' Diese Einstellung weist Next.js an, statische HTML-Dateien zu generieren, und images: { unoptimized: true } umgeht die Next.js-Bildoptimierung, die einen Server erfordert.

Wichtig: Wenn du Features nutzt, die einen Server erfordern (API Routes, Server Components mit Data Fetching usw.), musst du diese auf clientseitige Alternativen oder externe APIs umstellen.

Füge mobile-spezifische Skripte zu deinem 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"
  }
}

Teste den statischen Export mit:

bun run build

Du solltest einen out Ordner in der Wurzel deines Projekts. Dieser enthält alle statischen Dateien, die Capacitor in deine native App bundelt.

Capacitor 8 zu deinem Projekt hinzufügen

Um deine Next.js-App in einen nativen Mobile-Container zu verpacken, folge diesen Schritten:

Installiere Capacitor Core und CLI:

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

Installiere die gängigen Capacitor Plugins, die du wahrscheinlich brauchst:

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

Diese Plugins bieten essenzielle Features:

@capacitor/app: App-Lifecycle-Events verwalten (Foreground/Background, URLs)
@capacitor/keyboard: Tastaturverhalten auf Mobilgeräten steuern
@capacitor/splash-screen: Den nativen Splash Screen verwalten
@capacitor/preferences: Key-Value-Daten persistent speichern

Initialisiere Capacitor mit deinen Projektdetails:

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

Ersetze my-app mit deinem App-Namen und com.example.myapp mit deiner App-ID (Reverse-Domain-Notation).

Erstelle oder aktualisiere die capacitor.config.ts Datei mit der passenden 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;

Native Plattformen installieren:

bun add @capacitor/ios @capacitor/android

Native-Plattform-Ordner hinzufügen:

bunx cap add ios
bunx cap add android

Capacitor erstellt ios und android Ordner im Projekt-Root, die die nativen Projekte enthalten.

Um das Android-Projekt zu builden, benötigst du Android Studio. Für iOS brauchst du einen Mac mit Xcode.

Projekt builden und synchronisieren:

bun run mobile

Hier wird dein Custom Script ausgeführt, das das Next.js Projekt buildet und die statischen Dateien mit den nativen Plattformen synchronisiert.

Native Apps builden und deployen

Um deine native Mobile App zu builden und zu deployen, folge diesen Schritten: Für die iOS-Entwicklung benötigst du Xcode installiert, und für Android-Apps benötigst du Android Studio installiert. Wenn du deine App zudem in den App Stores veröffentlichen willst, musst du dich für das Apple Developer Program (iOS) bzw. die Google Play Console (Android) anmelden.

Native Projekte öffnen:

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

App bauen und ausführen:

android-studio-run

Warte in Android Studio, bis das Projekt bereit ist, und klicke dann auf den „Run“-Button, um die App auf einem verbundenen Gerät oder Emulator zu deployen.
Richte in Xcode dein Signing-Account ein, um die App auf einem echten Gerät zu deployen. Falls du das noch nicht gemacht hast, führt dich Xcode durch den Prozess (beachte, dass du im Apple Developer Program angemeldet sein musst). Sobald alles eingerichtet ist, klicke auf den „Play“-Button, um die App auf deinem Gerät zu starten.

Glückwunsch! Du hast deine Next.js Web-App erfolgreich auf einem mobilen Gerät deployt.

Aber Moment, es gibt während der Entwicklung auch einen schnelleren Weg...

Capacitor Live Reload

Während der Entwicklung kannst du Live Reload nutzen, um Änderungen sofort auf deinem mobilen Gerät zu sehen. So aktivierst du dieses Feature:

Finde deine lokale IP-Adresse:

Führe unter macOS folgenden Befehl im Terminal aus:
```
ipconfig getifaddr en0
```
Unter Windows:
```
ipconfig
```
Suche in der Ausgabe nach der IPv4-Adresse.

Aktualisiere dein capacitor.config.ts um auf deinen Development-Server zu zeigen:

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;

Ersetze YOUR_IP_ADDRESS mit deiner lokalen IP-Adresse (z. B. 192.168.1.100).

Übernimm die Änderungen in dein natives Projekt:

bunx cap copy

Der copy Der Befehl kopiert den Web-Ordner und die Konfigurationsänderungen in das native Projekt, ohne das gesamte Projekt zu aktualisieren.

Rebuild und Start der App auf deinem Gerät via Android Studio oder Xcode.

Sobald du nun Änderungen an deiner Next.js App vornimmst, lädt die mobile App automatisch neu, um diese zu übernehmen.

Hinweis: Wenn du neue Plugins installierst oder native Dateien änderst, musst du das native Projekt neu bauen, da Live Reloading nur für Web code Änderungen gilt.

Capacitor Plugins verwenden

Mit Capacitor Plugins kannst du von deiner Next.js App auf native Device-Features zugreifen. Schauen wir uns an, wie man den Share-Plugin als Beispiel nutzt:

Installiere das Share-Plugin:

bun add @capacitor/share

Aktualisiere die pages/index.js Datei, um das Share-Plugin zu nutzen:

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

Synchronisiere die Änderungen mit dem nativen Projekt:

Wie bereits erwähnt, müssen wir nach der Installation neuer Plugins einen Sync durchführen und die App anschließend neu auf das Gerät deployen. Nutze dazu diesen Befehl:

bun run mobile

Oder synchronisiere einfach ohne Rebuild:

bunx cap sync

Rebuild durchführen und die App auf deinem Device starten.

Wenn du jetzt auf den Button „Share now!“ klickst, öffnet sich der native Share-Dialog, mit dem du den Inhalt über andere Apps teilen kannst.

Als Nächstes kannst du die App auf iOS und Android mit Capgo Navigation und Transitions nativ wirken lassen und typische iOS-Layoutprobleme wie horizontalen Overflow oder abgeschnittene Safe Areas beheben. ## Native UI mit Capgo Native Navigation und Transitions

Ich arbeite schon seit Jahren mit Ionic um plattformübergreifende Apps zu bauen, aber die Integration mit Next.js ist oft umständlich und lohnt sich kaum, wenn du bereits Tailwind CSS 4.

Für ein natives Mobile-Feeling in einer Next.js + Capacitor App solltest du Capgo Plugins statt reiner Web-UI-Kits wie Konsta UI verwenden:

@capgo/capacitor-native-navigation — native Navbar, Liquid Glass Tab Bar auf iOS und ein Blur-Effekt für die Tab Bar auf Android. Dein Next.js Router verwaltet den Route-State; das Plugin übernimmt das native Chrome.
@capgo/capacitor-transitions — Page Transitions im Ionic-Stil und iOS Edge Swipe-Back in der WebView-Ebene, ohne das Ionic UI zu übernehmen.

Beides installieren:

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

Konfiguriere die native Navigation mit dem CSS Inset Mode, damit Web-Content die nativen Bars berücksichtigt:

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

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

Rendere eine Liquid Glass Tab Bar (iOS nutzt systemeigenes Rendering; Android nutzt einen geblurrten 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üge native Page Transitions in deine App Shell ein:

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

initTransitions({ platform: 'auto' });

Umschließe geroutete Seiten mit cap-router-outlet, cap-page, und cap-content, und rufe setDirection('forward') oder setDirection('back') bevor router.push() oder router.back(). Vermeide doppelte Web-Header oder -Footer, wenn die native Navigation diese Flächen übernimmt.

Hier findest du die vollständigen Guides: Verwendung von @capgo/capacitor-native-navigation und Verwendung von @capgo/capacitor-transitions.

Safe Areas mit Tailwind

Verwende für Device Safe Areas in Tailwind CSS @capgo/tailwind-capacitor (veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Utilities und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

Unter styles/globals.css:

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

Nutze Utilities wie pt-safe, pb-safe, und px-safe anstatt alles manuell env(safe-area-inset-*) von Hand. Das Projekt wird aktiv weiterentwickelt – falls etwas für dein Next.js-Setup fehlt, eröffne einen PR auf GitHub.

iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontaler Overflow)

Wenn Inhalte auf iOS abgeschnitten, verschoben oder horizontal scrollbar wirken, hilft es meist nicht, mehr overflow-x: hidden hinzuzufügen oder nur das Viewport-Tag zu ändern. Gehe diese Checks der Reihe nach durch.

Stelle sicher, dass das 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/): füge das Viewport-Meta-Tag in pages/_app.tsx, nicht _document.tsx (Next.js wendet Tags eventuell nicht so an, _document.tsx wie Sie es für das Viewport-Verhalten erwarten).

iOS Safe Area nur von einem Root-Wrapper aus handhaben

Erstelle eine einzige App-Shell und wende dort das Safe-Area-Padding 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);
}

Umschließe den gesamten Seiteninhalt mit .app-shellDoppeltes Safe-Area-Padding in Headern, Modals und Layout-Wrappern lässt das UI oft abgeschnitten oder zu groß wirken.

Mit @capgo/tailwind-capacitor, kannst du dasselbe Padding mit Utilities wie pt-safe pb-safe px-safe in dieser einen Shell ausdrücken.

Setze Capacitor iOS `contentInset` zu `never` zuerst

Unter capacitor.config.ts, deaktiviere lieber native Insets und überlasse CSS (oder der Native Navigation contentInsetMode: 'css') die Safe Area:

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

Kombination von Capacitor’s automatischen Content Insets mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.

Das tatsächlich überlaufende Element finden

Der übliche Übeltäter ist ein Element mit 100vw, Tailwind w-screen, einer festen Pixelbreite oder einem großen min-width.

Im 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 wann immer möglich. Viele Probleme mit horizontalem Overflow entstehen durch 100vw / w-screen, doppeltes Safe-Area-Padding oder einen Container mit fester Breite – nicht durch das Viewport-Meta-Tag selbst.

Performance-Optimierung

Um die Performance deiner Next.js und Capacitor App zu optimieren, solltest du diese Best Practices beachten:

Minimiere die App-Größe, indem du ungenutzte Dependencies und Assets entfernst.
Optimiere Bilder und andere Mediendateien, um die Ladezeiten zu verkürzen.
Nutze Lazy Loading für Komponenten und Pages, um die Performance beim ersten Laden zu verbessern.
Setze Server-Side Rendering (SSR) mit Next.js ein, um die Ladezeit und SEO deiner App zu verbessern.
Nutze die integrierten Optimierungen von Capacitor, wie Web View Caching und App Bundling.

Fazit

Du hast deine Next.js Web-App erfolgreich mit Capacitor 8 in native iOS- und Android-Apps umgewandelt. Dein Web-Code läuft nun nativ auf mobilen Geräten und hat Zugriff auf Device APIs.

Das hast du erreicht:

Next.js für Static Export konfiguriert
Capacitor 8 mit wichtigen Plugins hinzugefügt
Build und Deployment auf iOS- und Android-Simulatoren
Live Reload für die Entwicklung aktiviert
Typische iOS-Layoutprobleme behoben (Viewport, Safe Area, Overflow)
Native UI mit Capgo Native Navigation und Transitions hinzugefügt

Nächste Schritte:

Einrichten Capgo für Over-the-Air Updates ohne App Store Resubmission
Weitere native Plugins wie Camera, Geolocation oder Push Notifications hinzufügen
App-Icons und Splash Screens für die Produktion konfigurieren
App für die Einreichung im App Store und bei Google Play vorbereiten

Ein ganz neues Projekt starten? Schau dir an: Eine Next.js Mobile App von Grund auf bauen für eine Schritt-für-Schritt-Anleitung.

Ressourcen

Next.js-Dokumentation
@capgo/capacitor-native-navigation — Liquid Glass Tab Bar und native Bedienelemente
Capacitor 8 Dokumentation
@capgo/capacitor-transitions — Page Transitions, die sich nativ anfühlen
@capgo/tailwind-capacitor — Tailwind Safe-Area-Utilities für Capacitor
Capgo – Live Updates für Capacitor Apps

Erfahren Sie, wie Capgo Ihnen hilft, schneller bessere Apps zu bauen, Registrieren Sie sich für ein kostenloses Konto noch heute.

Weiter mit Convert Your Next.js App to iOS & Android with Capacitor 8

Wenn du es nutzt Next.js-App zu iOS & Android konvertieren mit Capacitor 8 Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails unter „Plugins hinzufügen oder aktualisieren“, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen und Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds.