Convertissez votre application Next.js en iOS & Android avec Capacitor 8

Introduction

Avez-vous une application web Next.js existante ? Dans ce guide, vous apprendrez à la transformer en applications mobiles natives iOS et Android en utilisant Capacitor 8 — la dernière version avec une meilleure performance 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 existant. Contrairement à React Native, vous n'avez pas besoin de réécrire quoi que ce soit — votre Next.js code fonctionne tel quel.

Ce que vous apprendrez :

Configurez votre application Next.js existante pour l'export statique
Ajoutez Capacitor 8 avec les plugins natifs essentiels
Construisez et testez sur les simulateurs iOS et Android
Enable live reload for faster development
Corriger les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement horizontal)
Add native-feeling UI with Capgo Native Navigation and Transitions

Vous souhaitez démarrer un nouveau projet à partir de zéro ? Consultez notre guide sur Construire une application mobile Next.js à partir de zéro.

Avantages de l'utilisation de Next.js et Capacitor

Code Reusabilité: Next.js vous permet d'écrire des composants réutilisables et de partager code entre vos applications web et mobiles, en économisant du temps et de l'effort de développement.
Performances: Next.js offre des optimisations de performance intégrées, comme le rendu côté serveur et la code segmentation, garantissant des temps de chargement rapides et une expérience utilisateur fluide.
Capacités Natives: Capacitor offre accès aux fonctionnalités natives du dispositif comme la caméra, la géolocalisation et bien plus, vous permettant de créer des applications mobiles riches en fonctionnalités.
Développement SimplifiéAvec Capacitor, vous pouvez développer et tester votre application mobile en utilisant des technologies web familières, 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 existant Xcode application
Xcode (pour le développement iOS, macOS uniquement)
Android Studio (pour le développement Android)

Configuring Your Next.js App for Mobile

La première étape consiste à configurer votre application Next.js pour l'exportation statique. Capacitor nécessite des fichiers HTML/JS/CSS statiques pour les assembler dans l'application native.

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

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

module.exports = nextConfig;

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

Important : Si vous utilisez des fonctionnalités qui nécessitent un serveur (API routes, composants de serveur avec récupération de données, etc.), vous devrez les réorganiser pour utiliser 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 exécutant :

bun run build

Vous devriez voir un out dossier à la racine de votre projet. Ce dossier contient tous les fichiers statiques que Capacitor rassemblera dans votre application native.

Ajouter Capacitor 8 à votre projet

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

Installez Capacitor core et CLI :

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

Installez les plugins Capacitor courants que vous aurez probablement besoin :

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

Ces plugins fournissent des fonctionnalités essentielles :

@capacitor/appGérer les événements de cycle d'application (avant-plan/arrière-plan, URLs)
@capacitor/clavier: Contrôler le comportement de la touche sur mobile
@capacitor/écran d'accueil: Gérer l'écran d'accueil natif
@capacitor/préférences: Store key-value data persistently

Initialiser Capacitor avec les détails de votre projet :

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

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

Créer ou mettre à 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;

Installer les plateformes natives :

bun add @capacitor/ios @capacitor/android

Ajouter les dossiers de plateformes natives :

bunx cap add ios
bunx cap add android

Capacitor créera ios et android des dossiers au niveau racine de votre projet contenant les projets natifs.

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

Construire et synchroniser votre projet :

bun run mobile

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

Construire et Déployer des Applications Mobiles

Pour construire et déployer votre application mobile native, suivez ces étapes : 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 de distribuer votre application sur l'app store, vous devez vous inscrire au programme Apple Developer pour iOS et au 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

Construire et exécuter l'application :

android-studio-run

Dans Android Studio, attendez que le projet soit prêt, puis cliquez sur le bouton « Exécuter » pour déployer l'application sur un appareil connecté ou un émulateur.
Dans Xcode, configurez votre compte de signature pour déployer l'application sur un appareil réel. Si vous n'avez pas déjà effectué cela, Xcode vous guidera tout au long du processus (notez que vous devez être inscrit au programme Apple Developer). Une fois configuré, cliquez sur le bouton « Lancer » pour exécuter l'application sur votre appareil connecté.

Félicitations ! Vous avez réussi à déployer votre application web Next.js sur un appareil mobile.

Mais attendez, il existe également une méthode plus rapide pour procéder pendant le développement...

Capacitor Live Reload

Pendant le développement, vous pouvez profiter de la rechargement en direct pour voir les 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, exécutez :
```
ipconfig
```
Cherchez l'adresse IPv4 dans la sortie.

Mettez à jour 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;

Remplacez YOUR_IP_ADDRESS avec votre adresse IP locale (par exemple, 192.168.1.100).

Appliquez les modifications à votre projet natif :

bunx cap copy

Le copy La commande copie le dossier web et les modifications de configuration vers le projet natif sans mettre à jour tout le projet.

Reconstruire et exécuter l'application sur votre appareil à l'aide d'Android Studio ou de Xcode.

Maintenant, chaque fois que vous apportez des modifications à votre application Next.js, l'application mobile se rechargera automatiquement pour refléter ces changements.

Note: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.

Utiliser des plugins Capacitor

Les plugins Capacitor vous permettent d'accéder aux fonctionnalités natives de votre appareil à partir de votre application Next.js. Explorons comment les utiliser. Partagez l'extension plugin de partage

Installez le plugin de partage :

bun add @capacitor/share

Mettre à jour le pages/index.js fichier à utiliser pour l'extension de partage :

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 modifications avec le projet natif :

Comme mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une opération de synchronisation et redéployer ensuite l'application sur notre appareil. Pour ce faire, exécutez la commande suivante :

bun run mobile

Ou synchronisez simplement sans reconstruire :

bunx cap sync

Reconstruire et exécuter l'application sur votre appareil.

Maintenant, lorsque vous cliquez sur le bouton « Partager maintenant ! », le dialogue de partage natif s'affichera, vous permettant de partager le contenu avec d'autres applications.

Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec Capgo de la navigation et des 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. ## Interface utilisateur native avec Capgo de la navigation native et des transitions

J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais l'intégration avec Next.js est hacky et rarement justifiée lorsque vous avez déjà Tailwind CSS 4.

Pour un sentiment mobile natif dans une application Next.js + Capacitor , utilisez les plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :

@capgo/capacitor-navigation native native — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur Next.js conserve l'état de la route ; le plugin possède la barre de chrome native.
@capgo/capacitor-transitions — Transition de page à la manière d'Ionic et swipe-back sur iOS dans la couche WebView, sans adopter l'UI d'Ionic.

Installez les deux :

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Configurez la navigation native avec le mode d'insertion 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 système-propriétaire ; 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 }) => {
  router.push(`/${id}`);
});

Add native page transitions in your 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-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') ou router.push() ou router.back()N'ajoutez pas de titres web ou de pieds de page lorsqu'une navigation native gère ces surfaces.

Voir les guides complets : Utilisation de @capgo/capacitor-navigation native and Utilisation de @capgo/capacitor-transitions.

Utiliser @__CAPGO_KEEP_0/CAPGO_KEEP_1__-transitions

For device safe areas in Tailwind CSS, use @capgo/tailwind-capacitor Publié sous le titre tailwind-capacitor sur npm). Il fournit safe-areas des outils et d'autres plugins Tailwind compatibles avec Capacitor :

bun add -D tailwind-capacitor

In styles/globals.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Utilisez des outils comme pt-safe, pb-safe, et px-safe au lieu de les ajouter env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration Next.js, ouvre une PR sur GitHub.

Résoudre 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 de overflow-x: hidden ou modifier seul la balise viewport ne résout généralement pas le problème. Passer par ces vérifications dans l'ordre.

Vérifiez que la balise meta viewport est appliquée correctement

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

import type { Viewport } from 'next';

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

Routage de Pages (pages/mettez la balise meta viewport dans pages/_app.tsx, pas _document.tsx (Next.js peut ne pas appliquer les balises de) _document.tsx Gérez l'espace sûr d'iOS à partir d'un seul wrapper racine

Gérer l'espace sûr d'iOS à partir d'un seul wrapper racine

Créez un noyau d'application unique et appliquez-y un padding de zone de sécurité — et non 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);
}

Wrappez tout le contenu de la page à l'intérieur .app-shellLes marges de sécurité dupliquées dans les en-têtes, les modaux et les enveloppes de mise en page rendent souvent l'interface utilisateur coupée ou trop grande.

Avec @capgo/tailwind-capacitor, vous pouvez exprimer la même marge avec des utilitaires comme pt-safe pb-safe px-safe sur cette seule coquille.

Définissez Capacitor iOS `contentInset` en premier `never` Dans

In capacitor.config.tspréférez l'insérer natif désactivé et laissez CSS (ou la navigation native) contentInsetMode: 'css'Propriétaire de la zone sécurisée :

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

Mélanger les Capacitor automatiques d'insertion de contenu avec CSS env(safe-area-inset-*) le padding est une cause courante de double espace.

Trouvez l'élément qui déborde vraiment

Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur de pixels fixe, ou une large min-width.

Dans l'inspecteur Web Safari, exécutez :

[...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-screen, des margeures de zone de sécurité dupliquées ou un conteneur à largeur fixe — pas de la balise meta viewport elle-même.

Optimisation de la Performance

Pour garantir une performance optimale de votre application Next.js et Capacitor , considérez les meilleures pratiques suivantes :

Réduisez la taille de l'application en supprimant les dépendances et les actifs non utilisés.
Optimisez les images et les fichiers multimédias pour réduire les temps de chargement.
Améliorez la charge de travail initiale en implémentant le chargement différé pour les composants et les pages.
Utilisez le rendu côté serveur (SSR) avec Next.js pour améliorer la vitesse de chargement de l'application et l'optimisation pour les moteurs de recherche (SEO).
Profitez des optimisations intégrées de Capacitor, telles que le cache de la vue web et le regroupement de l'application.

Conclusion

Vous avez réussi à convertir votre application web Next.js existante en applications natives iOS et Android à l'aide de Capacitor 8. Votre codebase web fonctionne maintenant nativement sur les appareils mobiles avec accès aux API de l'appareil.

Ce que vous avez accompli :

Configuré Next.js pour l'export statique
Added Capacitor 8 avec les plugins essentiels
Construit et déployé vers les simulateurs iOS et Android
Enabled live reload for development
Résolu les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement)
Ajout d'interface utilisateur native avec Capgo Navigation et transitions natives

Étapes suivantes :

Configurer Capgo pour les mises à jour hors ligne sans réévaluation de l'App Store
Ajoutez plus de plugins natifs comme la Caméra, la Géolocalisation ou les Notifications Push
Configure app icons and splash screens for production
Préparez votre application pour la soumission sur l'App Store et Google Play

Démarrer un nouveau projet ? Consultez Construire une application mobile Next.js à partir de zéro pour une prise en main guidée.

Ressources

Documentation Next.js
@capgo/capacitor-navigation-native — Barre de navigation Liquide et chrome natif
Capacitor 8 Documentation
@capgo/capacitor-transitions transition d'page avec un sentiment natif
@capgo/tailwind-capacitor — Utilitaires de zone sûre Tailwind pour Capacitor
Capgo - Live Updates for Capacitor Apps

Learn how Capgo can help you build better apps faster, inscrivez-vous à un compte gratuit aujourd'hui.

Continuez à partir de Convertir votre application Next.js en iOS & Android avec Capacitor 8

Si vous utilisez Convertir votre application Next.js en iOS & Android avec Capacitor 8 pour planifier le travail de plugin natif, connectez-l’avec Capgo Répertoire des plugins pour le flux de travail du produit dans Capgo Répertoire des plugins, Capacitor Plugins par Capgo pour les détails d'implémentation dans Capacitor Plugins par Capgo, Ajouter ou Mettre à jour les plugins pour les détails d'implémentation dans Ajouter ou Mettre à jour les plugins, Alternatives aux plugins d'entreprise Ionic pour le flux de travail du produit dans les alternatives Ionic Enterprise Plugin Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs

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