Ce tutoriel vous guidera dans la création d'une application mobile avec React et Capacitor. À la fin, vous saurez comment transformer une application web React.js en une application mobile native avec Capacitor, tout en ajoutant une sensation native grâce à Capgo Native Navigation and Transitions.
Capacitor permet de transformer facilement votre application web React.js en une application mobile native, sans nécessiter de modifications majeures ni l'apprentissage de nouvelles stratégies comme React Native.
Le processus comprend quelques étapes simples et, avant même que vous ne vous en rendiez compte, votre application React.js sera une application mobile pleinement fonctionnelle. Restez avec nous, nous vous accompagnons dans cette aventure.
Aperçu de Capacitor
CapacitorJS change la donne. Il s'intègre parfaitement à n'importe quel projet web et encapsule votre application dans une webview native tout en générant les projets Xcode et Android Studio. De plus, grâce à ses plugins, vous pouvez accéder aux fonctionnalités natives de l'appareil, comme la caméra, via un bridge JS.
Capacitor offre un moyen simple de créer une application mobile native sans difficulté ni courbe d'apprentissage abrupte. Son API simple et ses fonctionnalités épurées facilitent son intégration dans votre projet.
Configuration de votre application React.js
Utilisons la méthode la plus simple pour initialiser une application React. Nous allons utiliser le gestionnaire de paquets npm pour créer une nouvelle application React :
npx create-react-app my-appPour transformer notre projet en application mobile native, un export de notre application est requis.
Nous y reviendrons dans un instant. Tout d'abord, comprenons comment intégrer Capacitor dans notre application React.
Intégrer Capacitor à votre application React.js
Les étapes de configuration initiale peuvent sembler un peu détaillées, mais après cela, mettre à jour votre wrapper d'application natif devient aussi simple que d'exécuter une sync commande.
Tout d'abord, nous allons installer le Capacitor CLI comme dépendance de développement et le configurer dans notre projet. Lors de la configuration, acceptez les valeurs par défaut pour le nom et le bundle ID en appuyant sur « Entrée ».
Ensuite, nous allons installer le package principal ainsi que les packages nécessaires pour les plateformes iOS et Android.
Enfin, nous ajouterons les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de notre projet :
# 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 androidLe iOS et Android les répertoires sont désormais présents dans votre projet React.js.
Pour accéder au projet Android plus tard, installez Android Studio. Pour iOS, vous avez besoin d'un Mac et devez installer Xcode.
Ensuite, mettez à jour le webDir dans votre capacitor.config.json fichier comme illustré ci-dessous :
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Exécutez la commande de build et synchronisez votre projet avec Capacitor :
npm run build
npx cap syncLe npm run build commandera le build de votre projet React.js, tandis que npx cap sync alignera le code web aux emplacements précis des plateformes natives afin qu'il puisse être exécuté dans une application.
Maintenant, avec un peu de chance et sans erreur, votre app React.js devrait être prête à être lancée sur un appareil !
Build et déploiement de vos apps natives
Le développement d'apps iOS nécessite Xcode, et les apps Android nécessitent Android Studio. Si vous prévoyez de distribuer votre app sur les stores, vous devez vous inscrire au Apple Developer Program pour iOS et à la Google Play Console pour Android.
Le Capacitor CLI simplifie l'ouverture des deux projets natifs :
npx cap open ios
npx cap open androidUne fois vos projets natifs configurés, déployer votre app sur un appareil connecté est un processus simple.
Pour Android Studio, attendez que tout soit chargé, puis déployez votre app sur un appareil connecté.
Pour Xcode, configurez votre compte de signing pour déployer votre app sur un appareil réel plutôt que sur le simulateur. Une fois cela fait, appuyez simplement sur play pour lancer l'app sur l'appareil connecté, que vous pouvez choisir en haut.
Si tout s'est bien passé, vous aurez converti votre web app React.js en une application mobile native !
Capacitor Live Reload
Les frameworks de développement modernes incluent généralement le hot reload, et heureusement, vous pouvez avoir la même chose avec Capacitor mais sur votre appareil mobile!
Vous pouvez rendre votre application hébergée localement accessible via le live reload sur votre réseau en demandant à l'app Capacitor de charger le contenu depuis une URL spécifique.
Tout d'abord, déterminez votre adresse IP locale. Sur Mac, vous pouvez le faire en lançant ipconfig getifaddr en0 dans le terminal. Sur Windows, exécutez ipconfig et cherchez l'adresse IPv4.
Ensuite, demandez à Capacitor de charger l'app directement depuis le serveur en ajoutant un paramètre à votre capacitor.config.ts fichier :
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;Assurez-vous d'utiliser l'IP et le port corrects. Lancez npx cap copy pour appliquer ces changements à votre projet natif.
Une fois que vous aurez déployé votre app via Android Studio ou Xcode, tout changement dans votre app React sera automatiquement rechargé et affiché sur votre appareil !
Gardez à l'esprit que l'installation de nouveaux plugins, comme la caméra, nécessite un nouveau build de votre projet natif. En effet, les fichiers natifs auront changé et ne peuvent pas être mis à jour à la volée.
Utiliser les plugins Capacitor
Jetons un coup d'œil rapide à l'utilisation d'un plugin Capacitor. Installons-en un simple, le plugin Share, ce qui déclenche le dialogue de partage natif :
npm i @capacitor/sharePour l'utiliser, importez le package et appelez la share() fonction de notre application. Considérez le 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;Après avoir installé un nouveau plugin, n'oubliez pas de synchroniser à nouveau votre projet React en utilisant npx cap sync.
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec la navigation et les transitions Capgo, et corriger les problèmes de mise en page iOS courants qui causent des débordements horizontaux ou des safe areas rognées.
Une interface fluide avec Capgo Native Navigation et Transitions
J'ai travaillé pendant des années avec Ionic pour compiler des applications multiplateformes, mais l'intégrer à React est laborieux et rarement rentable si vous utilisez déjà Tailwind CSS.
Pour un rendu mobile natif dans une application React + Capacitor, utilisez des plugins Capgo plutôt que des kits UI web comme Konsta UI :
- @capgo/capacitor-native-navigation — une barre de navigation native, une tab bar Liquid Glass sur iOS, et un style de tab bar floutée sur Android. Votre React router gère l'état des routes ; le plugin gère l'interface native.
- @capgo/capacitor-transitions — des transitions de page façon Ionic et le swipe-back depuis le bord sur iOS dans la couche WebView, sans adopter l'UI Ionic.
Installez les deux :
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurez la navigation native avec le mode CSS inset pour que le contenu web respecte les barres natives :
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Affichez une tab bar Liquid Glass (iOS utilise le rendu du système ; Android utilise un arrière-plan WebView flouté) :
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}`);
});Ajoutez des transitions de page natives dans votre app shell :
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>;
}Enveloppez les pages routées dans cap-router-outlet, cap-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant de naviguer. Ne dupliquez pas les headers ou footers web lorsque la navigation native gère ces surfaces.
Consultez les guides complets : Utilisation de @capgo/capacitor-native-navigation et Utiliser @capgo/capacitor-transitions.
Safe areas avec Tailwind
Pour les safe areas de l'appareil avec Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas utilitaires et d'autres plugins Tailwind compatibles Capacitor :
bun add -D tailwind-capacitorDans src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des utilitaires tels que pt-safe, pb-safe, et px-safe au lieu de parsemer env(safe-area-inset-*) à la main. Le projet est activement développé — s'il manque quelque chose pour votre configuration React, ouvrez une PR sur GitHub.
Corriger les problèmes de mise en page iOS (viewport, zone sécurisée et débordement horizontal)
Si le contenu semble coupé, décalé ou défile horizontalement sur iOS, ajouter plus de overflow-x: hidden ou si le simple ajustement de la balise viewport ne suffit pas. Effectuez ces vérifications dans l'ordre.
Assurez-vous que la balise meta viewport est correctement appliquée
Ajoutez la balise meta viewport dans index.html inside <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérez la safe area iOS depuis un seul wrapper racine
Créez un shell d'application unique et appliquez-y le padding de la safe area — pas dans plusieurs composants imbriqués :
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);
}Enveloppez tout le contenu de la page dans .app-shell. Un padding de safe area dupliqué dans les headers, les modales et les wrappers de layout donne souvent l'impression que l'UI est rognée ou trop grande.
Avec @capgo/tailwind-capacitor, vous pouvez obtenir le même padding avec des utilitaires comme pt-safe pb-safe px-safe sur ce shell unique.
Configurez Capacitor iOS contentInset vers never d'abord
Dans capacitor.config.ts, préférez désactiver les insets natifs et laissez le CSS (ou la contentInsetMode: 'css') gèrent la safe area :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Combiner le content inset automatique de Capacitor avec le CSS env(safe-area-inset-*) le padding est une cause fréquente de double espacement.
Trouvez l'élément qui déborde réellement
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou un grand min-width.
Dans le Web Inspector de Safari, lancez :
[...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,
}));Avec Tailwind, remplacez w-screen par w-full dès que possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, d'un padding safe-area dupliqué, ou d'un conteneur à largeur fixe — et non de la balise meta viewport elle-même.
Conclusion
Capacitor offers a seamless means of building native apps based on an existing web project, providing a simple way to share code and have consistent UI.
Grâce à des technologies comme Capacitor, créer des applications mobiles à partir d'apps web React.js n'a jamais été aussi simple. Passez au niveau supérieur en développant des apps mobiles natives impressionnantes. Bon code !
Pour en savoir plus sur la façon d'accélérer votre processus de développement d'app, créez un compte gratuit today.
Continuez avec Building Mobile Apps with Pure React.js and Capacitor
Si vous utilisez Créer des applications mobiles avec React.js pur et Capacitor pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la fonctionnalité native dans la section Utiliser @capgo/capacitor-video-player, @capgo/capacitor-video-player pour les détails d'implémentation dans @capgo/capacitor-video-player, et Utilisation de @capgo/capacitor-native-navigation pour la fonctionnalité native dans Using @capgo/capacitor-native-navigation.
