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

Introduction

Vous disposez d'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 allez apprendre :

Configurez votre application Next.js existante pour l'exportation statique
Ajoutez Capacitor 8 avec les plugins natifs essentiels
Construire et tester sur les simulateurs iOS et Android
Activer la rechargement en direct pour un développement plus rapide
Résoudre les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement horizontal)
Ajouter une interface utilisateur ressemblant à celle des natives avec Capgo Navigation et Transitions Native

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

Avantages de l'utilisation de Next.js et Capacitor

Code Reutilisation :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 propose des optimisations de performances intégrées, telles que le rendu côté serveur et code de segmentation, garantissant des temps de chargement rapides et une expérience utilisateur fluide.
Capacités natives: Capacitor offre accès aux fonctionnalités de l'appareil natif comme la caméra, la géolocalisation et plus encore, vous permettant de créer des applications mobiles riches en fonctionnalités.
Simplification du Développement: Avec Capacitor, vous pouvez développer et tester votre application mobile en utilisant des technologies web familières, réduisant la courbe d'apprentissage et simplifiant le processus de développement.

Prérequis

Avant de commencer, assurez-vous d'avoir :

Node.js 18+ installé
Une application existante Next.js 15+ Xcode
(pour le développement iOS, macOS uniquement) un environnement de développement
Android Studio (pour le développement Android)

Configurer votre application Next.js pour les appareils mobiles

Le premier pas 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;

La output: 'export' configuration indique à Next.js de générer des fichiers HTML statiques, et images: { unoptimized: true } bypasses l'optimisation des images 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 refacturer celles-ci 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 au niveau racine de votre projet. Cela contient toutes les fichiers statiques que Capacitor bundlera dans votre application native.

Ajouter Capacitor 8 à votre projet

Pour emballer 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/app: Gérer les événements de cycle de vie de l'application (avant-plan/arrière-plan, URLs)
@capacitor/keyboard: Contrôlez le comportement du clavier sur mobile
@capacitor/écran de démarrage: Gérez l'écran de démarrage natif
@capacitor/préférences: Stockez des données de type clé-valeur de manière persistante

Initialisez Capacitor avec les détails de votre projet :

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

Remplacez my-app par le nom de votre application et com.example.myapp par 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 de plateforme native :

bunx cap add ios
bunx cap add android

Capacitor créera ios et android les dossiers à la 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.

Développement d'applications mobiles natives

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 distribuer votre application sur le magasin d'applications, 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

Construirez et exécuterez 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.
In Xcode, configurez votre compte de signature pour déployer l'application sur un appareil réel. Si vous n'avez pas fait cela avant, Xcode vous guidera tout au long du processus (notez que vous devez être inscrit dans le programme Apple Developer). Une fois configuré, cliquez sur le bouton « Jouer » 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 un moyen plus rapide de procéder pendant le développement...

Capacitor Live Reload

Pendant le développement, vous pouvez profiter de la mise à jour en temps réel 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
```
Recherchez l'adresse IPv4 dans la sortie.

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;

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

Appliquez les modifications à votre projet natif :

bunx cap copy

Le copy commande copie le dossier web et les modifications de configuration dans le projet natif sans mettre à jour l'ensemble du projet.

Reconstruit et exécutez l'application sur votre appareil en utilisant Android Studio ou Xcode.

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

Remarque : Si vous installez de nouveaux plugins ou apportez des modifications à des fichiers natifs, vous devrez reconstruire le projet natif car la rechargement en temps réel ne s'applique qu'aux modifications web code.

Using Capacitor Plugins

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

Installez le plugin de partage :

bun add @capacitor/share

Mettez à jour le pages/index.js fichier pour utiliser le plugin 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>
  );
}

Synchronisez 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 l'application sur notre appareil. Pour cela, exécutez la commande suivante :

bun run mobile

Ou synchronisez simplement sans reconstruire :

bunx cap sync

Reconstruit et exécutez l'application sur votre appareil.

Maintenant, lorsque vous cliquez sur le bouton « Partagez 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 ressemblant à celle d'un système d'exploitation avec Capgo Navigation et Transitions Native

J'ai travaillé pendant des années avec Ionic pour construire des applications cross-plateformes, mais intégrer Next.js est un peu hacky et rarement valable lorsque vous avez déjà Tailwind CSS 4.

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

@capgo/capacitor-navigation-native — barre de navigation native, Liquid Glass barre de tabs sur iOS, et un style de barre de tabs flou sur Android. Votre routeur Next.js conserve l'état des routes ; le plugin gère la barre de chrome native.
@capgo/capacitor-transitions — transitions de page à la manière d'Ionic et un retour arrière par swipe sur l'écran 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'insérion 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',
  },
});

Rendre une barre de tabs en verre liquide (iOS utilise la mise en page système ; Android utilise un arrière-plan flou de WebView) :

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 les transitions de page natives dans votre coquille d'application :

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-contentou appeler setDirection('forward') ou setDirection('back') avant router.push() ou router.back(). N'ajoutez pas les en-têtes ou les pieds de page natives lorsqu'une navigation native possède ces surfaces.

Consultez les guides complets : En utilisant @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.

Zones de sécurité avec Tailwind

Pour les zones de sécurité des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous le nom de tailwind-capacitor le npm). Il fournit safe-areas des utilitaires et d'autres plugins Tailwind compatibles avec 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 comme 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 Next.js, 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éfile horizontalement sur iOS, ajoutez plus overflow-x: hidden ou modifier le tag de vueport seul ne résout généralement pas le problème. Travaillez à travers ces vérifications dans l'ordre.

Assurez-vous que le tag meta de vueport est appliqué correctement

App Router (app/: export viewport de app/layout.tsx:

import type { Viewport } from 'next';

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

Pages Router (pages/: mettre le tag meta de vueport dans pages/_app.tsx, pas _document.tsx (Next.js peut ne pas appliquer les tags de la manière que vous attendez pour le comportement de vueport). _document.tsx 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 — et non dans plusieurs composants imbriqués :

Handle iOS safe area from one root wrapper only

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 à l'intérieur .app-shellLa mise en page de la zone de sécurité répétée dans les en-têtes, les modaux et les enveloppes de disposition peut souvent donner l'impression que l'interface utilisateur est coupée ou trop grande.

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

Définissez Capacitor iOS `contentInset` sur `never` premier

In capacitor.config.ts, préférez la mise en page native de la zone de sécurité désactivée et laissez CSS (ou la navigation native) gérer la zone de sécurité : contentInsetMode: 'css'In

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

Mélanger l'Capacitor automatique d'insertion de contenu avec CSS env(safe-area-inset-*) La mise en page en pixels est une cause courante de double espace.

Trouvez l'élément débordant réel

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 de 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,
  }));

En utilisant Tailwind, remplacez w-screen par w-full lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, de la duplication de la mise en page de la zone de sécurité, ou d'un conteneur à largeur fixe — et non de la balise meta de la zone de vue elle-même.

Optimisation de la performance

To ensure optimal performance of your Next.js and Capacitor application, consider the following best practices:

Réduisez la taille de l'application en supprimant les dépendances et les ressources inutilisées.
Optimisez les images et les autres fichiers multimédias pour réduire les temps de chargement.
Implémentez le chargement différé pour les composants et les pages pour améliorer les performances de chargement initiales.
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 bundling 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'exportation statique
Added Capacitor 8 avec les plugins essentiels
Construit et déployé vers les simulateurs iOS et Android
Activer le rechargement en direct pour le développement
Corrigé les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement)
Ajouté une interface utilisateur ressemblant à celle native avec Capgo Navigation et Transitions Native

Étapes suivantes :

Configurer Capgo pour les mises à jour hors ligne sans soumission de l'application sur l'app store
Ajouter plus de plugins natives comme la Caméra, la Géolocalisation ou les Notifications Push
Configurer les icônes et les écrans de démarrage de l'application pour la production
Préparer votre application pour la soumission sur l'App Store et Google Play

En créant un nouveau projet ? Consultez Créer une application mobile Next.js à partir de zéro pour une présentation guidée.

Ressources

Documentation Next.js
@capgo/capacitor-navigation-native — barre de navigation Liquid Glass et navigateur natif
Capacitor 8 Documentation
@capgo/capacitor-transitions — transitions de page ressenties comme natives
@capgo/tailwind-capacitor — utilitaires de zone sécurisée Tailwind pour Capacitor
Capgo - Mises à jour en temps réel pour les applications Capacitor

Apprenez comment Capgo peut vous aider à créer des applications meilleures et plus rapides. Inscrivez-vous pour 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-le avec Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou Mettre à jour les plugins pour les détails d'implémentation dans Ajouter ou Mettre à jour les plugins, Alternatives de plugins d'entreprise Ionic pour le flux de travail du produit dans les alternatives de plugins d'entreprise Ionic, et Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs.

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