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 base de code 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 mise en page 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 app 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, ce qui réduit le temps et l'effort 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 donne accès aux fonctionnalités natives de l'appareil comme la caméra, la géolocalisation et bien plus, vous permettant de créer des apps 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) fichier 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 buildVous 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/preferencesCes 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 outRemplacer 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.tsfichier 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 androidCapacitor 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 mobileCela 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:iosPour Android :
bun run mobile:androidOu directement avec Capacitor CLI :
bunx cap open ios
bunx cap open android- Compilez et lancez l'app :
-
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 signature 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.
Live Reload avec Capacitor
Pendant le développement, vous pouvez profiter du live reload pour voir vos modifications 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 :
ipconfigCherchez l'adresse IPv4 dans la sortie.
- Mettez à jour votre
capacitor.config.tspour 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 modifications à votre projet natif :
bunx cap copyLe copy La commande copie le dossier web et les modifications de configuration vers le projet natif sans mettre à jour tout le projet.
- Recompilez et lancez l'app sur votre appareil avec Android Studio ou Xcode.
Désormais, dès que vous modifiez votre app Next.js, l'app mobile se recharge automatiquement pour refléter ces modifications.
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 modifications 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. Voyons comment utiliser le plugin Share en guise d'exemple :
- Installez le plugin Share :
bun add @capacitor/share- Mettez à jour le
pages/index.jspour 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>
);
}- Synchronisez les changements avec le projet natif :
Comme mentionné plus haut, quand on installe de nouveaux plugins, il faut faire une sync puis redéployer l'application sur notre appareil. Pour cela, lancez la commande suivante :
bun run mobileOu synchronisez simplement sans reconstruire :
bunx cap sync- Reconstruisez et lancez l'app sur votre appareil.
Désormais, quand vous cliquez sur le bouton « Share now! », la boîte de dialogue de partage native s'affiche, vous permettant de partager le contenu avec d'autres apps.
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 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 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 }) => {
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-capacitorDans 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 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
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 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: 'out',
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.
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 au 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
- Compilation et déploiement sur les simulateurs iOS et Android
- Activation du live reload pour le développement
- Correction des problèmes de layout iOS courants (viewport, safe area, overflow)
- Ajout d'une UI au rendu natif avec Capgo Native Navigation and Transitions
Prochaines étapes :
- Configuration Capgo pour des live updates sans nouvelle soumission 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 l'App Store et Google Play
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 d'onglets Liquid Glass et chrome natif
- Capacitor 8 Documentation
- @capgo/capacitor-transitions — transitions de page au rendu 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 aujourd'hui.
Foire aux questions
Comment convertir une application Next.js en application mobile ?
Configurez l'output sur export dans next.config pour que Next.js génère un site statique, ajoutez Capacitor ainsi que les plateformes iOS et Android, pointez webDir vers le dossier out, puis lancez npx cap sync et ouvrez les projets natifs. Les fonctionnalités côté serveur comme les routes API doivent être déplacées vers un backend séparé. Après la release, les live updates Capgo déployez vos changements web sans nouvelle revue sur les stores.
Continuer depuis « Convertir votre application Next.js en iOS et 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.
