Convertissez votre app Next.js en iOS et Android avec Capacitor 8

Introduction

Vous avez déjà une application web Next.js ? Dans ce guide, vous apprendrez à la transformer en applications mobiles natives iOS et Android en utilisant Capacitor 8 — la dernière version avec des performances améliorées et de nouvelles fonctionnalités.

Capacitor enveloppe votre application web dans un conteneur natif, vous donnant accès aux API de l'appareil comme la caméra, le système de fichiers et les notifications push, tout en conservant votre codebase React actuelle. Contrairement à React Native, vous n'avez rien à réécrire — votre code Next.js s'exécute tel quel.

Ce que vous allez apprendre :

Configurer votre application Next.js actuelle pour l'export statique
Ajouter Capacitor 8 avec les plugins natifs essentiels
Compiler et tester sur des simulateurs iOS et Android
Activer le live reload pour un développement plus rapide
Corriger les problèmes de layout iOS courants (viewport, safe area, overflow horizontal)
Ajouter une UI au feeling natif avec Capgo Native Navigation et Transitions

Vous souhaitez lancer un nouveau projet de zéro ? Consultez notre guide sur Créer une application mobile Next.js de zéro.

Avantages de l'utilisation de Next.js et Capacitor

Réutilisabilité avec Code: Next.js vous permet d'écrire des composants réutilisables et de partager code entre vos applications web et mobiles, économisant ainsi du temps et des efforts de développement.
Performance: Next.js propose des optimisations de performance intégrées, comme le rendu côté serveur et le splitting code, garantissant des temps de chargement rapides et une expérience utilisateur fluide.
Capacités nativesCapacitor permet d'accéder aux fonctionnalités natives de l'appareil comme la caméra, la géolocalisation et bien plus, pour créer des applications mobiles riches en fonctionnalités.
Développement simplifié: Avec Capacitor, vous pouvez développer et tester votre application mobile avec vos technologies web habituelles, ce qui réduit la courbe d'apprentissage et simplifie le processus de développement.

Prerequisites

Avant de commencer, assurez-vous d'avoir :

Node.js 18+ installé
Un Next.js 15+ application
Xcode (pour le développement iOS, macOS uniquement)
Android Studio (pour le développement Android)

Configurer votre application Next.js pour le mobile

La première étape consiste à configurer votre application Next.js pour l'export statique. Capacitor a besoin de fichiers HTML/JS/CSS statiques pour les inclure dans le bundle de l'application native.

Ouvrez votre next.config.js (ou next.config.ts) et ajoutez la configuration d'export :

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

Le output: 'export' ce paramètre indique à Next.js de générer des fichiers HTML statiques, et images: { unoptimized: true } contourne l'optimisation d'images de Next.js, qui nécessite un serveur.

Important : Si vous utilisez des fonctionnalités qui nécessitent un serveur (routes API, server components avec récupération de données, etc.), vous devrez les refactoriser vers des alternatives côté client ou des API externes.

Ajoutez des scripts spécifiques au mobile à votre package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Testez l'export statique en lançant :

bun run build

Vous devriez voir un dossier out à la racine de votre projet. Il contient tous les fichiers statiques que Capacitor intégrera dans le bundle de votre application native.

Ajouter Capacitor 8 à votre projet

Pour encapsuler votre application Next.js dans un conteneur mobile natif, suivez ces étapes :

Installez le core Capacitor et CLI :

bun add @capacitor/core
bun add -D @capacitor/cli

Installez les plugins Capacitor courants dont vous aurez probablement besoin :

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences

Ces plugins offrent des fonctionnalités essentielles :

@capacitor/app: Gérer les événements du cycle de vie de l'app (premier plan/arrière-plan, URLs)
@capacitor/keyboard: Contrôler le comportement du clavier sur mobile
@capacitor/splash-screen: Gérer le splash screen natif
@capacitor/preferences: Store key-value data persistently

Initialisez Capacitor avec les détails de votre projet :

bunx cap init my-app com.example.myapp --web-dir out

Remplacer my-app avec le nom de votre app et com.example.myapp avec l'ID de votre application (notation de domaine inversée).

Créez ou mettez à jour le capacitor.config.ts fichier avec la configuration appropriée :

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true,
    },
  },
};

export default config;

Installez les plateformes natives :

bun add @capacitor/ios @capacitor/android

Ajoutez les dossiers des plateformes natives :

bunx cap add ios
bunx cap add android

Capacitor va créer les ios et android dossiers à la racine de votre projet contenant les projets natifs.

Pour compiler le projet Android, vous avez besoin d' Android Studio. Pour iOS, vous avez besoin d'un Mac avec Xcode.

Compilez et synchronisez votre projet :

bun run mobile

Cela exécute votre script personnalisé qui compile le projet Next.js et synchronise les fichiers statiques avec les plateformes natives.

Compiler et déployer des apps natives

Pour compiler et déployer votre app mobile native, suivez ces étapes : Pour développer des apps iOS, vous devez avoir Xcode installé, et pour les apps Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez de distribuer votre app sur les stores, vous devez vous inscrire à l'Apple Developer Program pour iOS et à la Google Play Console pour Android.

Ouvrez les projets natifs :

Pour iOS :

bun run mobile:ios

Pour Android :

bun run mobile:android

Ou directement avec Capacitor CLI :

bunx cap open ios
bunx cap open android

Compilez et lancez l'app :

android-studio-run

Dans Android Studio, attendez que le projet soit prêt, puis cliquez sur le bouton « Run » pour déployer l'app sur un appareil connecté ou un émulateur.
Dans Xcode, configurez votre compte de signing pour déployer l'app sur un appareil réel. Si vous ne l'avez jamais fait, Xcode vous guidera (notez que vous devez être inscrit au Apple Developer Program). Une fois configuré, cliquez sur le bouton « Play » pour lancer l'app sur votre appareil connecté.

Félicitations ! Vous avez déployé avec succès votre web app Next.js sur un appareil mobile.

Mais attendez, il existe aussi un moyen plus rapide de faire cela pendant le développement...

Live Reload Capacitor

Pendant le développement, vous pouvez profiter du live reloading pour voir vos changements instantanément sur votre appareil mobile. Pour activer cette fonctionnalité, suivez ces étapes :

Trouvez votre adresse IP locale :

Sur macOS, exécutez la commande suivante dans le terminal :
```
ipconfig getifaddr en0
```
Sur Windows, lancez :
```
ipconfig
```
Cherchez l'adresse IPv4 dans le résultat.

Mettez à jour votre capacitor.config.ts pour pointer vers votre serveur de développement :

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
};

export default config;

Remplacer YOUR_IP_ADDRESS avec votre adresse IP locale (ex : 192.168.1.100).

Appliquez les changements à votre projet natif :

bunx cap copy

Le copy la commande copie le dossier web et les changements de configuration vers le projet natif sans mettre à jour l'intégralité du projet.

Recompilez et lancez l'app sur votre appareil via Android Studio ou Xcode.

Désormais, dès que vous modifiez votre app Next.js, l'app mobile se rechargera automatiquement pour refléter ces changements.

Note : si vous installez de nouveaux plugins ou modifiez des fichiers natifs, vous devrez recompiler le projet natif car le live reload ne s'applique qu'aux changements code web.

Utiliser les plugins Capacitor

Les plugins Capacitor vous permettent d'accéder aux fonctionnalités natives de l'appareil depuis votre application Next.js. Explorons comment utiliser le plugin Partager le plugin comme exemple :

Installer le plugin Share :

bun add @capacitor/share

Mettre à jour le pages/index.js pour utiliser le plugin Share :

import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';

export default function Home() {
  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 className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href="https://nextjs.org">Capgo!</a>
        </h1>

        <p className={styles.description}>
          <h2>Cool channel</h2>
          <button onClick={() => share()}>Share now!</button>
        </p>
      </main>
    </div>
  );
}

Synchroniser les changements avec le projet natif :

Comme mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une opération de sync puis redéployer l'app sur notre appareil. Pour ce faire, lancez la commande suivante :

bun run mobile

Ou simplement synchroniser sans reconstruire :

bunx cap sync

Reconstruire et lancer l'app sur votre appareil.

Désormais, lorsque vous cliquez sur le bouton « Share now! », la boîte de dialogue de partage native apparaîtra, vous permettant de partager le contenu avec d'autres apps.

Ensuite, vous pouvez rendre l'application plus native sur iOS et Android grâce à la navigation et aux transitions Capgo, et corriger les problèmes de mise en page iOS courants qui provoquent un débordement horizontal ou des safe areas rognées. ## Une UI au rendu natif avec Capgo Native Navigation and Transitions

J'ai travaillé pendant des années avec Ionic pour développer des applications multiplateformes, mais son intégration à Next.js est bancale et rarement rentable quand vous avez déjà Tailwind CSS 4.

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

@capgo/capacitor-native-navigation — une navbar native, une tab bar Liquid Glass sur iOS et un style de tab bar floutée sur Android. Votre routeur Next.js conserve 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 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 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 }) => {
  router.push(`/${id}`);
});

Ajoutez des transitions de page natives dans votre app shell :

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

Enveloppez les pages routées dans cap-router-outlet, cap-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant router.push() ou router.back(). 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 styles/globals.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 Next.js, 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 l'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

App Router (app/): export viewport depuis app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

Pages Router (pages/): placez la balise meta viewport dans pages/_app.tsx, et non _document.tsx (Next.js peut ne pas appliquer les tags comme _document.tsx vous l'attendez pour le comportement du viewport).

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,
#__next {
  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 le native inset et laissez le CSS (ou la navigation native) contentInsetMode: 'css') gérer la safe area :

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

Mélanger l'automatic content inset 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.

Optimisation des performances

Pour garantir des performances optimales de votre application Next.js et Capacitor, suivez ces bonnes pratiques :

Réduisez la taille de l'app en supprimant les dépendances et les assets inutilisés.
Optimisez les images et autres fichiers média pour réduire les temps de chargement.
Implémentez le lazy loading pour les composants et les pages afin d'améliorer la performance du chargement initial.
Utilisez le server-side rendering (SSR) avec Next.js pour booster la vitesse de chargement et le SEO de l'app.
Profitez des optimisations intégrées de Capacitor, comme le cache de la web view et le bundling de l'app.

Conclusion

Vous avez converti avec succès votre application web Next.js en apps natives iOS et Android grâce à Capacitor 8. Votre codebase web s'exécute désormais nativement sur mobile avec un accès aux API de l'appareil.

Ce que vous avez accompli :

Configuration de Next.js pour l'export statique
Ajout de Capacitor 8 avec les plugins essentiels
Build et déploiement sur simulateurs iOS et Android
Activation du live reload pour le développement
Correction des problèmes de layout iOS (viewport, safe area, overflow)
Ajout d'une UI native avec Capgo Native Navigation and Transitions

Prochaines étapes :

Configuration Capgo pour les live updates sans resoumission sur les stores
Ajouter d'autres plugins natifs comme Camera, Geolocation ou Push Notifications
Configurer les icônes et splash screens pour la production
Préparer votre app pour la publication sur les stores

Vous lancez un nouveau projet ? Consultez Créer une app mobile Next.js de zéro pour un tutoriel guidé.

Ressources

Documentation Next.js
@capgo/capacitor-native-navigation — Barre de navigation Liquid Glass et chrome natif
Capacitor 8 Documentation
@capgo/capacitor-transitions — Transitions de page au feeling natif
@capgo/tailwind-capacitor — Utilitaires Tailwind safe-area pour Capacitor
Capgo - Live Updates pour les apps Capacitor

Learn how Capgo can help you build better apps faster, créez un compte gratuit today.

Continuer après Convertir votre app Next.js en iOS & Android avec Capacitor 8

Si vous utilisez Convertissez votre application Next.js en applications iOS et Android avec Capacitor 8 pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.