In diesem Tutorial lernst du, wie du mit React und Capacitor eine mobile App erstellst. Am Ende weißt du, wie du eine React.js Web-App mittels Capacitor in eine native mobile App verwandelst und mit Capgo Native Navigation und Transitions für ein natives Feeling sorgst.
Capacitor ermöglicht die einfache Transformation deiner React.js Web-App in eine native mobile App, ohne dass tiefgreifende Änderungen oder das Erlernen neuer Strategien wie React Native nötig sind.
Der Prozess umfasst nur wenige einfache Schritte, und schon ist deine React.js App eine voll funktionsfähige mobile App. Bleib also dran, während wir dich auf diesem Weg begleiten.
Capacitor Übersicht
CapacitorJS ist ein echter Game-Changer. Es lässt sich nahtlos in jedes Webprojekt integrieren und verpackt deine App in eine native WebView, während es gleichzeitig das native Xcode- und Android-Studio-Projekt erzeugt. Dank der Plugins kannst du zudem über eine JS-Bridge auf native Gerätefunktionen wie die Kamera zugreifen.
Capacitor bietet einen unkomplizierten Weg, eine native mobile App ohne großen Aufwand oder steile Lernkurve zu erstellen. Das einfache API und die schlanke Funktionalität machen die Integration in dein Projekt zum Kinderspiel.
Deine React.js-App einrichten
Wir nehmen die einfachste Methode, um eine React-App zu starten: Mit dem npm Package Manager erstellen wir eine neue React-App:
npx create-react-app my-appUm unser Projekt in eine native mobile App zu verwandeln, ist ein Export unserer App erforderlich.
Dazu 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 Setup-Schritte sind vielleicht etwas detailliert, aber danach ist das Update deines nativen App-Wrappers so einfach wie das Ausführen eines sync Befehls.
Zuerst installieren wir das Capacitor CLI als Dev-Dependency und richten es in unserem Projekt ein. Bestätige während des Setups die Standardwerte für Name und Bundle ID einfach mit der „Enter“-Taste.
Als Nächstes installieren wir das Core-Paket sowie die relevanten Pakete für iOS und Android.
Zuletzt fügen wir die Plattformen hinzu, und Capacitor erstellt für jede Plattform einen Ordner in unserem Projektverzeichnis:
# 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 androidDie ios und android Die Verzeichnisse sind nun in deinem React.js-Projekt vorhanden.
Um später auf das Android-Projekt zuzugreifen, installiere Android Studio. Für iOS benötigst du einen Mac und solltest Xcode.
Als Nächstes aktualisiere den webDir in deiner 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 syncDie npm run build Der Befehl baut dein React.js-Projekt, während npx cap sync die Web-code an den richtigen Stellen der nativen Plattformen platziert werden, damit sie in einer App ausgeführt werden können.
Mit etwas Glück und ohne Fehler sollte deine React.js-App nun bereit für den Launch auf einem Gerät sein!
Deine nativen Apps bauen und deployen
Die Entwicklung von iOS-Apps erfordert Xcode, und für Android-Apps benötigst du Android Studio. Wenn du deine App in App Stores veröffentlichen willst, musst du dich für das Apple Developer Program (iOS) und die Google Play Console (Android) anmelden.
Das Capacitor CLI vereinfacht das Öffnen beider Native Projects:
npx cap open ios
npx cap open androidSobald deine Native Projects eingerichtet sind, ist das Deployment auf ein verbundenes Gerät ein unkomplizierter Prozess.
Warte in Android Studio, bis alles geladen ist, und deploye deine App dann auf ein verbundenes Gerät.
Richte in Xcode dein Signing-Account ein, um die App auf einem echten Gerät statt nur im Simulator zu deployen. Klicke danach einfach auf Play, um die App auf deinem verbundenen Gerät zu starten, das du oben auswählen kannst.
Wenn alles geklappt hat, hast du deine React.js Web-App erfolgreich in eine native Mobile App verwandelt!
Capacitor Live Reload
Moderne Frameworks bieten meist Hot Reload, und zum Glück bekommst du das Gleiche mit Capacitor, aber direkt auf deinem mobilen Gerät!
Du kannst deine lokal gehostete App über Live Reload in deinem Netzwerk verfügbar machen, indem die Capacitor App den Content von einer spezifischen URL lädt.
Ermittle zuerst deine lokale IP-Adresse. Auf einem Mac kannst du das mit folgendem Befehl machen: ipconfig getifaddr en0 im Terminal. Unter Windows führe diesen Befehl aus: ipconfig und suche nach der IPv4-Adresse.
Weise Capacitor danach an, die App direkt vom Server zu laden, indem du einen weiteren Parameter zu deinem hinzufügst: capacitor.config.ts Datei ein:
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;Stelle sicher, dass die IP und der Port korrekt sind. Führe aus npx cap copy um diese Änderungen auf dein Native Build anzuwenden.
Sobald 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!
Beachte jedoch: Wenn neue Plugins installiert werden, wie zum Beispiel die Kamera, ist ein Rebuild deines Native Build erforderlich. Das liegt daran, dass sich die nativen Dateien geändert haben und nicht on-the-fly aktualisiert werden können.
Capacitor Plugins verwenden
Schauen wir uns kurz an, wie man ein Capacitor Plugin nutzt. Installieren wir ein einfaches, das: Share Plugin, was den nativen Share-Dialog öffnet:
npm i @capacitor/shareUm es zu nutzen, importiere das Package und rufe die entsprechende share() Funktion in unserer App auf. Schau dir dazu die App.js an:
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 denke daran, dein React-Projekt erneut mit zu synchronisieren: npx cap sync.
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-Feeling-UI mit Capgo Native Navigation und Transitions
Ich arbeite seit Jahren mit Ionic an plattformübergreifenden Apps, aber die Integration mit React ist 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 verwenden:
- @capgo/capacitor-native-navigation — native Navbar, Liquid Glass Tab Bar auf iOS und ein verschwommener 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 im WebView-Layer, ohne das Ionic UI zu übernehmen.
Beide installieren:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfiguriere die native Navigation mit dem CSS Inset Mode, damit der Web-Content die nativen Bars respektiert:
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-Backdrop):
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 deinen 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>;
}Geroutete Pages wrappen in cap-router-outlet, cap-page, und cap-content, und aufrufen setDirection('forward') oder setDirection('back') vor der Navigation. Vermeide doppelte 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 auf Geräten in Tailwind CSS verwende @capgo/tailwind-capacitor (veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Utilities und weitere 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 sie überall env(safe-area-inset-*) von Hand einzufügen. Das Projekt wird aktiv entwickelt – falls etwas für dein React-Setup fehlt, eröffne einen PR auf GitHub.
iOS-Layout-Probleme beheben (Viewport, Safe Area, Horizontal Overflow)
Falls Inhalte auf iOS abgeschnitten, verschoben oder horizontal scrollbar erscheinen, hilft das Hinzufügen von mehr overflow-x: hidden oder das bloße Anpassen des Viewport-Tags behebt das Problem meist nicht. Gehe diese Checks der Reihe nach durch.
Achte darauf, dass das Viewport-Meta-Tag korrekt gesetzt ist
Füge das Viewport-Meta-Tag in index.html innerhalb von <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />iOS Safe Area nur über einen Root-Wrapper handhaben
Erstelle einen einzigen 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-shellDoppelte Safe-Area-Padding-Werte in Headern, Modals und Layout-Wrappern führen oft dazu, dass die UI abgeschnitten oder zu groß wirkt.
Mit @capgo/tailwind-capacitor, kannst du dasselbe Padding mit Utilities wie pt-safe pb-safe px-safe auf dieser einen Shell.
Setze Capacitor iOS contentInset zu never zuerst
Unter capacitor.config.ts, deaktiviere lieber native Insets und überlasse CSS (oder Native Navigation contentInsetMode: 'css') die Safe Area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Das Mischen des automatischen Content Insets von Capacitor mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.
Das Element mit dem echten Overflow 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,
}));Ersetze bei Tailwind w-screen mit w-full wenn möglich. Viele horizontale Overflow-Probleme 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 eine nahtlose Möglichkeit, native Apps auf Basis bestehender Webprojekte zu erstellen – einfach, um code zu teilen und ein konsistentes UI zu gewährleisten.
Dank Technologien wie Capacitor war das Erstellen von Mobile Apps aus React.js Web-Apps noch nie so einfach. Nutze deine Web-Dev-Skills, um beeindruckende native Mobile Apps zu bauen. Happy coding!
Erfahre hier mehr darüber, wie du deinen App-Entwicklungsprozess beschleunigen kannst, melde dich für ein kostenloses Konto an – heute.
Weiterlesen: Mobile Apps mit Pure React.js und Capacitor bauen
Wenn Sie ... verwenden Mobile Apps bauen mit Pure React.js und Capacitor um natives Medien- 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 das Implementierungsdetail in @capgo/capacitor-live-activities, @capgo/capacitor-video-player verwenden für die native Funktion in „@capgo/capacitor-video-player verwenden“, @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player, und Verwendung von @capgo/capacitor-native-navigation für die native Funktionalität bei der Nutzung von @capgo/capacitor-native-navigation.
