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

Introduction

Vous avez 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 performance améliorée 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 code Next.js 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
Construisez et testez sur les simulateurs iOS et Android
Activez la rechargement en direct pour un développement plus rapide
Réparez les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement horizontal)
Ajoutez une interface utilisateur ressemblant à celle des appareils avec Capgo Navigation et Transitions natifs

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

Avantages de l'utilisation de Next.js et Capacitor

La reutilisabilité de Code: 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.
Performance: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
Capacités natives: Capacitor vous donne accès aux fonctionnalités de dispositif natif comme la caméra, la géolocalisation et plus encore, 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, 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+ l'application
Xcode (pour le développement iOS, macOS uniquement)
Android Studio (pour le développement Android)

Configuration de 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)

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

module.exports = nextConfig;

Le output: 'export' Cette configuration indique à Next.js de générer des fichiers HTML statiques, et images: { unoptimized: true } désactive 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 à la racine de votre projet. Cela contient tous les fichiers statiques que Capacitor bundlera dans votre application native.

Ajout de Capacitor 8 à votre projet

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

Installez le noyau Capacitor 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ôler le comportement du clavier sur les appareils mobiles
@capacitor/splash-screen : Gérer l'écran de splash natif
@capacitor/preferences : Stocker des données 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 Avec votre ID d'application (notation de domaine inversée).

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 et ios dossiers au niveau de votre projet contenant les projets natives. android Pour construire le projet Android, vous avez besoin de

Android Studio . Pour iOS, vous avez besoin d'un Mac avecXcode Create or update the __CAPGO_KEEP_0__ file with the proper configuration:.

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 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 l'app store, vous devez vous inscrire au programme Apple Developer pour iOS et au Google Play Console pour Android.

Ouvrir 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

En 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 émulateur.
En 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 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
```
Exécutez sur Windows :
```
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

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

Rebâtissez 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 rebâtir le projet natif car la rechargement en direct ne s'applique qu'aux modifications web code.

Utiliser les Capacitor Plugins

Capacitor plugins vous permettent d'accéder aux fonctionnalités de périphérique natives à partir de 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 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

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 à une application native avec Capgo Navigation et Transitions Native

J'ai travaillé pendant des années avec Ionic pour construire des applications cross-plateformes, mais intégrer Ionic avec Next.js est 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-native-navigation — 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 gère la barre de chrome native.
@capgo/capacitor-transitions — transitions de page de style Ionic et swipe-back sur l'arrière de l'écran sur iOS dans la couche WebView, sans adopter la 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',
  },
});

Rendre une barre de tab en verre liquide (iOS utilise la mise en page système ; Android utilise un fond de fenêtre 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}`);
});

Ajoutez des 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 <ion-header> et <ion-footer> , et appelez <ion-nav-push> ou <ion-nav-pop> avant ou après . cap-router-outlet, cap-pageN'écrasez pas les en-têtes ou les pieds de page web lorsqu'une navigation native contrôle ces surfaces. cap-contentConsultez les guides complets : setDirection('forward') En utilisant @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation setDirection('back') Configurez la navigation native avec le mode d'insertion CSS pour que le contenu web respecte les barres natives : router.push() Rendre une barre de tab en verre liquide (iOS utilise la mise en page système ; Android utilise un fond de fenêtre WebView flou) : router.back()Ajoutez des transitions de page natives dans votre coquille d'application :

Enveloppez les pages routées dans <ion-header> et <ion-footer> , et appelez <ion-nav-push> ou <ion-nav-pop> avant ou après . Using @capgo/capacitor-native-navigation And En utilisant @capgo/capacitor-transitions.

Zones de sécurité avec Tailwind

Pour les zones de sécurité du dispositif dans Tailwind CSS, utilisez @capgo/tailwind-capacitor Publié sous tailwind-capacitor sur npm. Il fournit safe-areas des utilitaires et d'autres plugins Tailwind compatibles avec Capacitor :

bun add -D tailwind-capacitor

En utilisant 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-*) à la main. 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 disposition iOS (Vueport, Zone de sécurité, et débordement horizontal)

Si le contenu semble coupé, décalé ou déplaçable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster seul le tag de vueport ne suffit généralement pas. Travaille à travers ces vérifications dans l'ordre.

Assurez-vous que le tag de métadonnées 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/): placez le tag de métadonnées de vueport dans pages/_app.tsx, pas _document.tsx (Next.js peut ne pas appliquer les balises comme attendu pour le comportement de la vue). _document.tsx Gérer l'espace sûr 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 — pas dans plusieurs composants imbriqués :

Enveloppez tout le contenu de la page à l'intérieur de

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

La mise en forme de l'espace sûr dupliquée dans les en-têtes, les modaux et les enveloppes de disposition rend souvent l'interface utilisateur coupée ou trop grande. .app-shellAvec

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorSur cette coquille unique. pt-safe pb-safe px-safe Définissez __CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` true `never` premier

Dans capacitor.config.ts, préfèrez l'insérer nativement désactivé et laissez CSS (ou la navigation native) gérer la zone de sécurité : contentInsetMode: 'css'Mélanger les marges automatiques de __CAPGO_KEEP_0__ avec CSS

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trouvez l'élément qui déborde vraiment

Le coupable habituel est un élément utilisant

, Tailwind 100vw, une largeur fixe en pixels, ou une w-screenDans l'inspecteur Web de Safari, exécutez : min-width.

Avec Tailwind, remplacez

[...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 with w-full lorsque possible. Beaucoup d'issues de débordement horizontal proviennent de 100vw / w-screenune duplication de la marge de sécurité de l'aire sûre, ou d'un conteneur de largeur fixe — pas de la balise meta de la vue d'ensemble 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 inutilisés.
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 la mise en page côté serveur (SSR) avec Next.js pour accroître 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 existante Next.js 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
Ajouté Capacitor 8 avec des plugins essentiels
Construit et déployé sur les simulateurs iOS et Android
Activé la 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 des natives avec Capgo Native Navigation et Transitions

Étapes suivantes :

Configurer Capgo pour les mises à jour hors ligne sans résubmission 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éparez votre application pour la soumission sur l'App Store et Google Play

Débutant 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 chrome natif
Capacitor 8 Documentation
@capgo/capacitor-transitions — transitions de page ressemblant à celles du navigateur
@capgo/tailwind-capacitor — Utilités de zone sûre de Tailwind pour Capacitor
Capgo - Mises à jour en temps réel pour les applications Capacitor

Découvrez comment Capgo peut vous aider à créer des applications meilleures et plus rapides s'inscrire à 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 du plugin natif, connectez-le 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 de Plugins Entreprise Ionic pour le flux de travail du produit dans Alternatives de Plugins Entreprise Ionic, et Capgo Bâtisseurs Natifs pour le flux de travail du produit dans Capgo Bâtisseurs Natifs.

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