Dans ce tutoriel, nous allons commencer avec une nouvelle React app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.
Capacitor allows you to easily convert your React web application into a native mobile app without significant modifications or learning a new skill like React Native.
Avec juste quelques étapes simples, la plupart des applications React peuvent être transformées en applications mobiles.
Ce tutoriel vous guidera tout au long du processus, en commençant par une nouvelle application React et puis en incorporant Capacitor pour entrer dans le domaine des applications mobiles natives. Vous pouvez également utiliser Capgo Native Navigation, Transitions et tailwind-capacitor pour les zones de sécurité.
À propos de Capacitor
CapacitorJS est un changement de jeu ! Vous pouvez l'intégrer facilement dans tout projet web, et il enveloppera votre application dans une vue web native, générant ainsi le projet Xcode et Android Studio natif pour vous. De plus, ses plugins vous donnent accès aux fonctionnalités de dispositif natif comme la caméra via un pont JS.
Avec Capacitor, vous obtenez une application mobile native fantastique sans aucune mise en place compliquée ou courbe d'apprentissage raide. Sa fine API et sa fonctionnalité épurée rendent l'intégration dans votre projet un jeu d'enfant. Croyez-moi, vous serez impressionné par la facilité avec laquelle vous pouvez obtenir une application native complète avec Capacitor !
Préparation de votre application React
Bien qu'il existe diverses méthodes pour initier les applications React, allons-y pour la plus simple dans ce tutoriel qui fournit une application React vierge :
npx create-react-app my-appPour créer une application mobile native, nous avons besoin d'un export de notre projet. Ainsi, ajoutons un script simple dans notre package.json qui peut être utilisé pour construire et exporter le projet React :
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Vous pouvez maintenant exécuter npm run build sans aucune inquiétude, et vous devriez pouvoir repérer un dossier frais sorti à la racine de votre projet.
Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.
Ajouter Capacitor à votre application React
Pour emballer n'importe quelle application web dans un conteneur mobile natif, nous devons suivre quelques étapes initiales, mais ensuite, c'est aussi simple que d'exécuter une seule commande. sync command.
Tout d'abord, nous pouvons installer le Capacitor CLI as a development dependency, and then set it up within our project. During the setup, you can press “enter” to accept the default values for name and bundle ID.
Finalement, nous pouvons ajouter les plateformes, et __CAPGO_KEEP_0__ créera des dossiers pour chaque plateforme à la racine de notre projet:
Enfin, nous pouvons ajouter 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 androidÀ ce stade, vous devriez pouvoir observer de nouvelles ios et android les dossiers de votre projet React.
C'est réellement des projets natifs !
Pour accéder au projet Android ultérieurement, vous devez installer Android Studio. Pour iOS, vous avez besoin d'un Mac et devriez installer Xcode.
De plus, vous devriez trouver un capacitor.config.ts un fichier dans votre projet, qui contient certaines configurations fondamentales Capacitor utilisées lors de la synchronisation. La seule chose dont vous devez vous soucier est le webDirqui doit pointer vers le résultat de votre commande de build. Actuellement, elle est inexacte.
Pour rectifier cela, ouvrez le capacitor.config.json et mettez à jour le webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Vous pouvez essayer en exécutant les commandes suivantes :
npm run build
npx cap syncLa première commande npm run build Construira simplement votre projet React et exporterait la build statique.
Alors que la deuxième commande npx cap sync syncrera tous les web code dans les bons endroits des plateformes natives afin qu'ils soient affichés dans une application.
syncronisera tous les web __CAPGO_KEEP_0__ dans les bons endroits des plateformes natives afin qu'ils puissent être affichés dans une application. De plus, la commande de synchronisation pourrait mettre à jour les plateformes natives et installer des plugins, donc lorsque vous installez un nouveau Capacitor plugins, il est temps de relancer npx cap sync encore.
Sans vous en rendre compte, vous êtes maintenant effectivement terminé, alors voyons l'application sur un appareil !
Construire et déployer des applications natives
Pour développer des applications iOS, vous devez avoir Xcode installé, et pour les applications Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez distribuer votre application sur l'app store, vous devez vous inscrire au programme Apple Developer pour iOS et au Google Play Console pour Android.
Si vous êtes nouveau dans le développement mobile natif, vous pouvez utiliser le Capacitor CLI pour ouvrir facilement les projets natifs :
npx cap open ios
npx cap open androidUne fois que vous avez configuré vos projets natifs, déployer votre application sur un appareil connecté est facile. Dans Android Studio, il vous suffit d'attendre que tout soit prêt, et vous pouvez déployer votre application sur un appareil connecté sans modifier les paramètres. Voici un exemple :
In Xcode, vous devez configurer votre compte de signature pour déployer votre application sur un appareil réel au lieu du simulateur. Si vous n'avez pas déjà effectué cela, Xcode vous guide à travers le processus (mais encore une fois, vous devez être inscrit au programme des développeurs). Une fois cela fait, vous pouvez simplement appuyer sur 'play' pour exécuter l'application sur votre appareil connecté, que vous pouvez sélectionner en haut. Voici un exemple :
Félicitations ! Vous avez réussi à déployer votre application web React sur un appareil mobile. Voici un exemple :
Attendez, il y a aussi une façon plus rapide de faire cela pendant le développement…
Capacitor Live Reload
À ce stade, vous êtes probablement habitué à avoir la mise à jour en temps réel avec tous les frameworks modernes, et la bonne nouvelle est que vous pouvez avoir la même fonctionnalité sur un appareil mobile avec un minimum d'effort !
Activer l'accès à votre application localement hébergée avec rechargement en direct sur votre réseau en faisant en sorte que l'application Capacitor charge le contenu à partir de l'URL spécifique.
La première étape consiste à déterminer votre adresse IP locale. Si vous utilisez un Mac, vous pouvez trouver cela en exécutant la commande suivante dans le terminal :
ipconfig getifaddr en0Sur Windows, exécutez :
ipconfigEnsuite, recherchez l'adresse IPv4.
Nous pouvons instruire Capacitor à charger l'application directement depuis le serveur en ajoutant une autre entrée à notre capacitor.config.ts fichier :
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'out',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Assurez-vous d'utiliser l'adresse IP et le port corrects, j'ai utilisé le port React par défaut dans cet exemple.
Maintenant, nous pouvons appliquer ces modifications en les copiant vers notre projet natif :
npx cap copyLe copy commande est similaire à syncmais elle ne fonctionnera que copiez les modifications apportées au dossier web et la configuration, sans mettre à jour le projet natif.
Vous pouvez maintenant déployer votre application une fois de plus à l'aide d'Android Studio ou Xcode. Après cela, si vous modifiez quelque chose dans votre application React, l'application se rechargera automatiquement et affichera les modifications !
Prenez en compte que si vous installez de nouveaux plugins comme la caméra, il est toujours nécessaire de reconstruire votre projet natif. C'est parce que les fichiers natifs sont modifiés, et cela ne peut pas être fait en temps réel.
Notez que vous devez utiliser l'IP et le port corrects dans votre configuration. Le bloc code ci-dessus montre le port React par défaut pour des fins de démonstration.
Utilisation des plugins Capacitor
Examinons comment utiliser un plugin Capacitor en action, que nous avons mentionné quelques fois avant. Pour cela, nous pouvons installer un plugin relativement simple en exécutant :
npm i @capacitor/shareRien de particulier n'est fait avec le plugin de partagemais cela affiche tout de même le dialogue de partage natif ! Pour cela, nous n'avons besoin que d'importer le package et d'appeler la share() fonction de notre application. Changeons le src/App.js en
import React from 'react';
import { Share } from '@capacitor/share';
function App() {
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>
<h1>Welcome to React and Capacitor!</h1>
<p>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</div>
);
}
export default App;Comme mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une opération de synchronisation et redéployer l'application sur notre appareil. Pour cela, exécutez la commande suivante :
npx cap syncAprès avoir cliqué sur le bouton, vous pouvez voir le dialogue de partage natif en action !
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec Capgo de navigation et de transitions, et corriger les problèmes de mise en page iOS courants qui entraînent un débordement horizontal ou des zones de sécurité coupées.
UI natif avec Capgo de Navigation et de Transitions
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais l'intégration avec React est hacky et rarement justifiée lorsque vous avez déjà Tailwind CSS.
Pour un sentiment natif mobile dans une application React + Capacitor , utilisez les plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation native — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur React conserve l'état des routes ; le plugin gère la barre de chrome native.
- @capgo/capacitor-transitions — transitions de page à l'Ionic et le balayage arrière 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 d'inset CSS 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',
},
});Afficher une barre d'onglets de verre liquide (iOS utilise une rendu propriétaire du système ; Android utilise un arrière-plan WebView flou).
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}`);
});Add native page transitions in your 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-pageet cap-content, et appelez setDirection('forward') ou setDirection('back') Avant de naviguer. N'ajoutez pas de titres ou de pieds de page web si la navigation native les gère.
Voir les guides complets : Utiliser @capgo/capacitor-navigation-native et Utiliser @capgo/capacitor-transitions.
Zones de sécurité avec Tailwind
For device safe areas in Tailwind CSS, use @capgo/tailwind-capacitor (publié comme tailwind-capacitor sur npm). Il fournit safe-areas outils et autres plugins Tailwind compatibles avec Capacitor:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des outils tels que pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration React, ouvre une PR sur GitHub.
Fixer les problèmes de mise en page iOS (Vueport, Zone de sécurité, et Débordement horizontal)
Si le contenu semble coupé, décalé ou déroulable horizontalement sur iOS, ajouter plus overflow-x: hidden ou modifier seul la balise viewport ne résout généralement pas le problème. Passons par ces vérifications dans l'ordre.
Assurez-vous que la balise meta de vueport est appliquée correctement
Ajoutez la balise meta de vueport dans index.html à l'intérieur <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérer l'espace sûr d'iOS à partir d'un seul enveloppe racine
Créez une coquille d'application unique et appliquez-y la mise en forme de l'espace sûr — 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);
}Entourez tout le contenu de la page .app-shellLa mise en page de sécurité dupliquée dans les en-têtes, les modaux et les enveloppes de mise en page peut rendre l'interface utilisateur trop grande ou coupée.
Avec @capgo/tailwind-capacitor, vous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.
Fixez Capacitor iOS contentInset à never first
Dans capacitor.config.tspréférez l'insérer nativement désactivé et laissez CSS (ou la navigation native) contentInsetMode: 'css'Propriétaire de la zone de sécurité :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mélanger Capacitor’s mise automatique de contenu avec CSS env(safe-area-inset-*) Le coupable habituel est un élément utilisant
Trouvez l'élément qui déborde réellement
, une largeur de pixels fixe, ou une large 100vw, Tailwind w-screenune largeur fixe de pixels, ou une grande min-width.
Exécutez dans l'Inspecteur Web de Safari :
[...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 lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screenPas de padding de zone de sécurité dupliquée ou d'un conteneur à largeur fixe — pas de la balise meta viewport elle-même.
Conclusion
Capacitor est une excellente option pour créer des applications natives à partir d'un projet web existant, offrant une façon simple de partager code et de maintenir une interface utilisateur cohérente.
Et avec l'ajout de Capgo, il est même plus facile d'ajouter des mises à jour en temps réel à votre application, vous assurant que vos utilisateurs aient toujours accès aux dernières fonctionnalités et correctifs de bogues.
Si vous souhaitez apprendre à ajouter Capgo à votre application React, consultez l'article suivant.
Continuez à partir de Créer des applications mobiles avec React et Capacitor
Si vous utilisez Créer des applications mobiles avec React et Capacitor pour planifier l'automatisation CI/CD, connectez-l’avec Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs Capgo Intégrations pour le flux de travail du produit dans Capgo Intégrations Intégration CI/CD pour le détail d'implémentation dans Intégration CI/CD, et GitHub Actions Intégrations pour le détail d'implémentation dans GitHub Actions Intégrations
