Aller au contenu principal
Tutoriel

Créer des applications mobiles avec React.js pur et Capacitor

Un guide pour transformer une application web React.js en application mobile native à l’aide de Capacitor, en y ajoutant Capgo Native Navigation, Transitions et les bonnes pratiques de mise en page iOS.

Créer des applications mobiles avec React.js pur et Capacitor Capgo : illustration du blog

Ce tutoriel vous guide pas à pas dans la création d'une application mobile avec React et Capacitor. À la fin, vous saurez transformer une application web React.js en application mobile native avec Capacitor, et lui donner un rendu natif grâce à Capgo Native Navigation and Transitions.

Capacitor permet de transformer facilement votre application web React.js en application mobile native, sans modifications majeures ni apprentissage de nouvelles approches comme React Native.

Le processus se déroule en quelques étapes simples et, en un rien de temps, votre application React.js sera une application mobile pleinement fonctionnelle. Restez avec nous, on vous guide tout au long du parcours.

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-app

Pour transformer notre projet en application mobile native, un Exporter 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 android

Le 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 tel que présenté 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 sync

Le npm run build la commande va compiler votre projet React.js, tandis que npx cap sync alignera le web code aux bons endroits des plateformes natives afin qu’il puisse être exécuté dans une application.

Maintenant, avec un peu de chance et sans erreur, votre application React.js devrait être prête à être lancée sur un appareil !

Compiler et déployer vos applications natives

Le développement d'applications iOS nécessite Xcode, et les applications Android requièrent Android Studio. Si vous prévoyez de distribuer votre application sur les stores, vous devez vous inscrire au Apple Developer Program pour iOS et à la Google Play Console pour Android.

Le Capacitor CLI simplifie le processus d'ouverture des deux projets natifs :

npx cap open ios
npx cap open android

Une fois vos projets natifs configurés, le déploiement de votre application sur un appareil connecté est un processus simple.

Pour Android Studio, attendez que tout soit chargé, puis déployez votre application sur un appareil connecté.

Pour Xcode, configurez votre compte de signature pour déployer votre application sur un appareil réel plutôt que sur le simulateur. Une fois cela fait, appuyez simplement sur lecture pour exécuter l'application sur votre appareil connecté, que vous pouvez sélectionner en haut.

Si tout s’est bien passé, vous avez converti votre application web React.js en application mobile native !

Live Reload avec Capacitor

Les frameworks de développement modernes intègrent généralement le hot reload, et heureusement, vous pouvez en profiter avec Capacitor mais sur votre appareil mobile!

Vous pouvez rendre votre application hébergée localement accessible avec le live reload sur votre réseau en configurant l’application Capacitor pour 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 autre 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 exacts. Lancez npx cap copy pour appliquer ces changements à notre projet natif.

Une fois votre app redéployée via Android Studio ou Xcode, toute modification de votre app React sera automatiquement rechargée et affichée dans votre app !

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, qui ouvre la boîte de dialogue de partage native :

npm i @capacitor/share

Pour l’utiliser, importez le package et appelez la fonction share() correspondante depuis notre application. Pensez à 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 l’installation d’un nouveau plugin, n’oubliez pas de resynchroniser 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 relève du bricolage et en vaut rarement la peine quand vous avez déjà Tailwind CSS.

Pour un rendu mobile natif dans une application React + Capacitor, utilisez les plugins Capgo plutôt que des kits UI web comme Konsta UI :

  • @capgo/capacitor-native-navigation — une navbar native, une barre d'onglets Liquid Glass sur iOS et une barre d'onglets au style flouté sur Android. Votre routeur React conserve l'état des routes ; le plugin gère l'habillage natif.
  • @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 sync

Configurez 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 barre d'onglets Liquid Glass (iOS utilise le rendu du système ; Android utilise un fond 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-capacitor

Dans 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 le simple ajustement de la balise viewport ne règle généralement pas le problème. 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 à l'intérieur <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 offre un moyen simple et fluide de compiler des apps natives à partir d'un projet web existant, avec la possibilité de partager facilement code et de conserver une UI cohérente.

Grâce à des technologies comme Capacitor, créer des applications mobiles à partir d'apps web React.js n'a jamais été aussi simple. Faites passer vos compétences en développement web au niveau supérieur en concevant des apps mobiles natives impressionnantes. Bon code !

Pour en savoir plus sur les moyens d'accélérer le développement de votre app, créez un compte gratuit aujourd'hui.

Continuer la lecture de Créer des applications mobiles avec React.js pur et 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.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.