Dieses Tutorial führt dich Schritt für Schritt durch die Entwicklung einer mobilen Anwendung mit React und Capacitor. Am Ende weißt du, wie du eine React.js-Web-App in eine native Mobile-App mit Capacitor verwandelst und mit Capgo Native Navigation und Transitions ein natives Gefühl vermittelst.
Capacitor ermöglicht die einfache Umwandlung deiner React.js-Web-App in eine native Mobile-App, ohne dass du große Änderungen vornehmen oder neue Strategien wie React Native lernen musst.
Der Prozess umfasst nur wenige einfache Schritte, und im Handumdrehen ist deine React.js-App eine voll funktionsfähige Mobile-App. Bleib also dran, während wir dich auf dieser Reise begleiten.
Capacitor Übersicht
CapacitorJS ist ein Gamechanger. Es lässt sich nahtlos in jedes Webprojekt integrieren und kapselt deine App in eine native Webview, während es das native Xcode- und Android-Studio-Projekt generiert. Darüber hinaus kannst du über seine Plugins auf native Gerätefunktionen wie die Kamera über eine JS-Bridge zugreifen.
Capacitor bietet einen unkomplizierten Weg, eine native Mobile-App zu erstellen, ohne großen Aufwand oder eine steile Lernkurve. Seine einfache API und die schlanken Funktionen machen es leicht, es in dein Projekt zu integrieren.
Deine React.js-App einrichten
Wir starten mit der einfachsten Methode, um eine React-Anwendung zu initialisieren. Wir nutzen den npm-Paketmanager, um eine neue React-App zu erstellen:
npx create-react-app my-appUm unser Projekt in eine native Mobile-App zu verwandeln, ist ein Export unserer App erforderlich.
Darauf kommen wir gleich zurück. Zuerst schauen wir uns an, wie wir Capacitor in unsere React-App integrieren.
Capacitor in deine React.js-App integrieren
Die ersten Einrichtungsschritte sind vielleicht etwas detailliert, aber danach ist das Aktualisieren deines nativen App-Wrappers so einfach wie das Ausführen eines sync Befehl.
Zuerst installieren wir das Capacitor CLI als Entwicklungabhängigkeit und richten es in unserem Projekt ein. Akzeptiere während der Einrichtung die Standardwerte für Name und Bundle-ID, indem du „Enter“ drückst.
Als Nächstes installieren wir das Core-Paket sowie die relevanten Pakete für die iOS- und Android-Plattformen.
Zum Schluss fügen wir die Plattformen hinzu, und Capacitor erstellt Ordner für jede Plattform in unserem Projektstammverzeichnis:
# Install the Capacitor CLI locally
npm install -D @capacitor/cli
# Initialize Capacitor in your React project
npx cap init
# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android
# Add the native platforms
npx cap add ios
npx cap add androidDer iOS und Android Verzeichnisse sind jetzt in Ihrem React.js-Projekt vorhanden.
Um später auf das Android-Projekt zuzugreifen, installieren Sie Android Studioinstallieren. Für iOS brauchst du einen Mac und solltest Xcode.
Als Nächstes aktualisieren Sie die webDir in deinem capacitor.config.json Datei wie unten gezeigt:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Führe den Build-Befehl aus und synchronisiere dein Projekt mit Capacitor:
npm run build
npx cap syncDer npm run build Befehl baut dein React.js-Projekt, während npx cap sync das Web-code an den richtigen Stellen der nativen Plattformen platziert, damit es in einer App ausgeführt werden kann.
Jetzt, mit etwas Glück und ohne Fehler, sollte deine React.js-App bereit für den Start auf einem Gerät sein!
Deine Native Apps bauen und deployen
Die Entwicklung von iOS-Apps erfordert Xcode, und Android-Apps benötigen Android Studio. Wenn Sie Ihre App im App Store veröffentlichen möchten, müssen Sie sich für das Apple Developer Program (iOS) und die Google Play Console (Android) registrieren.
Die Capacitor CLI vereinfacht das Öffnen beider nativer Projekte:
npx cap open ios
npx cap open androidSobald Ihre nativen Projekte eingerichtet sind, ist die Bereitstellung Ihrer App auf einem verbundenen Gerät ein unkomplizierter Vorgang.
In Android Studio warten Sie, bis alles geladen ist, und stellen Sie Ihre App dann auf einem verbundenen Gerät bereit.
In Xcode richten Sie Ihr Signing-Konto ein, um Ihre App auf einem echten Gerät statt nur im Simulator bereitzustellen. Danach klicken Sie einfach auf Play, um die App auf Ihrem verbundenen Gerät auszuführen, das Sie oben auswählen können.
Wenn alles gut gegangen ist, haben Sie Ihre React.js-Web-App in eine native mobile Anwendung umgewandelt!
Capacitor Live Reload
Moderne Entwicklungsframeworks bieten in der Regel Hot Reload, und glücklicherweise können Sie dasselbe mit Capacitor nutzen, aber auf Ihrem mobilen Gerät!
Sie können Ihre lokal gehostete Anwendung mit Live Reload in Ihrem Netzwerk zugänglich machen, indem die Capacitor-App den Inhalt von einer bestimmten URL lädt.
Bestimmen Sie zunächst Ihre lokale IP-Adresse. Auf einem Mac können Sie dies tun, indem Sie ausführen ipconfig getifaddr en0 im Terminal. Auf Windows führen Sie aus ipconfig und suche nach der IPv4-Adresse.
Weise danach Capacitor an, die App direkt vom Server zu laden, indem du einen weiteren Parameter zu deinem capacitor.config.ts Datei:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Achte darauf, die korrekte IP und den Port zu verwenden. Führe aus npx cap copy um diese Änderungen in unserem nativen Projekt anzuwenden.
Wenn du deine App erneut über Android Studio oder Xcode deployst, werden alle Änderungen in deiner React-App automatisch neu geladen und in deiner App angezeigt!
Denk daran: Wenn neue Plugins installiert werden, z. B. die Kamera, ist ein Rebuild deines nativen Projekts erforderlich. Das liegt daran, dass sich die nativen Dateien geändert haben und nicht auf dem Laufenden aktualisiert werden können.
Capacitor Plugins verwenden
Schauen wir uns kurz an, wie man ein Capacitor-Plugin verwendet. Installieren wir ein einfaches, das Share-Plugin, das den nativen Share-Dialog aufruft:
npm i @capacitor/shareUm es zu verwenden, importiere das Paket und rufe die jeweilige share() Funktion aus unserer App. Beachte die App.js:
import { Share } from '@capacitor/share';
function ShareButton() {
const share = async () => {
await Share.share({
title: 'React App',
text: 'Visit this React App',
url: 'http://localhost:3000',
dialogTitle: 'Share with...'
});
};
return (
<button onClick={share}>
Share
</button>
);
}
export default ShareButton;Nach der Installation eines neuen Plugins dein React-Projekt erneut mit npx cap sync.
Als Nächstes kannst du die App auf iOS und Android mit Capgo Navigation und Transitions nativer wirken lassen und typische iOS-Layoutprobleme beheben, die horizontalen Overflow oder abgeschnittene Safe Areas verursachen.
Native-Feeling-UI mit Capgo Native Navigation und Transitions
Ich arbeite schon seit Jahren mit Ionic um plattformübergreifende Apps zu bauen, ist die Integration mit React jedoch oft umständlich und lohnt sich kaum, wenn man bereits Tailwind CSS.
Für ein natives Mobile-Feeling in einer React + Capacitor App solltest du Capgo Plugins statt reiner Web-UI-Kits wie Konsta UI nutzen:
- @capgo/capacitor-native-navigation — native Navbar, Liquid Glass Tab Bar auf iOS und ein geblurrter Tab-Bar-Stil auf Android. Dein React 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 syncKonfiguriere 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 }) => {
navigate(`/${id}`);
});Füge native Page Transitions in deine App Shell ein:
import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
export function AppShell() {
const navigate = useNavigate();
const outletRef = useRef<HTMLElement>(null);
useEffect(() => {
if (outletRef.current) {
setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
}
}, []);
const openSettings = () => {
setDirection('forward');
navigate('/settings');
};
return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}Umschließe geroutete Seiten mit cap-router-outlet, cap-page, und cap-content, und rufe setDirection('forward') oder setDirection('back') bevor du navigierst. Dupliziere keine Web-Header oder -Footer, wenn die native Navigation diese Bereiche bereits übernimmt.
Hier findest du die vollständigen Guides: Verwendung von @capgo/capacitor-native-navigation und Verwendung von @capgo/capacitor-transitions.
Safe Areas mit Tailwind
Für Safe Areas von Geräten in Tailwind CSS verwende @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-capacitorUnter src/index.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-*) manuell. Das Projekt wird aktiv entwickelt – falls etwas für dein React-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
Füge das viewport-Meta-Tag in hinzu index.html innerhalb <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />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,
#root {
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: 'build',
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.
Fazit
Capacitor bietet einen nahtlosen Weg, um native Apps auf Basis eines bestehenden Web-Projekts zu erstellen und code einfach zu teilen, um eine konsistente UI zu gewährleisten.
Dank Technologien wie Capacitor ist es noch nie einfacher gewesen, mobile Anwendungen aus React.js-Web-Apps zu erstellen. Heben Sie Ihre Web-Entwicklungsfähigkeiten auf das nächste Level, indem Sie beeindruckende native Mobile-Apps entwickeln. Viel Spaß beim Coden!
Erfahren Sie mehr darüber, wie Sie Ihren App-Entwicklungsprozess beschleunigen können, Registrieren Sie sich für ein kostenloses Konto noch heute.
Machen Sie weiter mit Building Mobile Apps with Pure React.js und Capacitor
Wenn du es nutzt Mobile Apps bauen mit Pure React.js und Capacitor , um natives Media- und Interface-Verhalten zu planen, verbinde es mit @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities, Verwendung von @capgo/capacitor-video-player für die native Funktion bei Verwendung von @capgo/capacitor-video-player, @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player und Verwendung von @capgo/capacitor-native-navigation für die native Funktion bei Verwendung von @capgo/capacitor-native-navigation.
