Convertir 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 à l'aide de Capacitor 8 — la dernière version avec une meilleure performance et de nouvelles fonctionnalités.

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing React codebase. Unlike React Native, you don’t need to rewrite anything — your Next.js code runs as-is.

wrappe 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 fonctionne comme tel.

What you’ll learn:
Add Capacitor 8 with essential native plugins
Ajoutez Capacitor 8 avec les plugins natifs essentiels
Construisez et testez sur les simulateurs iOS et Android
Activez la rechargement en direct pour une mise au point plus rapide
Add native-feeling UI with Capgo Native Navigation and Transitions

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.

Benefits of Using Next.js and Capacitor

Code Reusability: Next.js enables you to write reusable components and share code between your web and mobile apps, saving development time and effort.
Performances: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
: Next.js propose des optimisations de performances intégrées, telles que le rendu côté serveur et la segmentation de code, garantissant des temps de chargement rapides et une expérience utilisateur fluide.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
: Capacitor vous donne accès aux fonctionnalités de dispositif natives comme la caméra, la géolocalisation, et plus encore, vous permettant de créer des applications mobiles riches en fonctionnalités.: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

: 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.

Avant de commencer, assurez-vous d'avoir :

Node.js 18+ installé
Un projet Next.js existant Next.js 15+ une 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) 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 Next.js qui nécessite un serveur.

Important : Si vous utilisez des fonctionnalités qui nécessitent un serveur (routes API, 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'exportation 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.

Intégrer 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 dont 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 de la touche sur mobile
@capacitor/splash-screen: Gérer l'écran de splash natif
@capacitor/preferences: Stocker des données clés-valeurs de manière persistante

Initialiser Capacitor avec vos détails de projet :

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

Remplacer my-app par votre nom d'application et com.example.myapp par 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 ios et android des dossiers au niveau de votre projet contenant les projets natifs.

To 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 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 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

Construirez et exécutez 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 dans le programme Apple Developer). Une fois configuré, cliquez sur le bouton « Play » 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 une méthode plus rapide pour effectuer cela 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
```
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 copie le dossier web et les modifications de configuration vers le projet natif sans mettre à jour tout le projet.

Reconstruire 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.

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.

Utilisation des plugins Capacitor

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

Installez le plugin de partage :

bun add @capacitor/share

Mettez à jour le fichier pour utiliser le plugin de partage : pages/index.js Synchronez les modifications avec le projet natif :

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

Rebuild and run the app on your device using Android Studio or Xcode.

As mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une opération de synchronisation et puis redéployer 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.

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas. ## Native-feeling UI with Capgo Native Navigation and Transitions

## Interface utilisateur ressemblant à une application native avec __CAPGO_KEEP_1__ Navigation et Transitions Native 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 valable lorsque vous avez déjà.

For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

Pour un sentiment mobile natif dans une application Next.js + capgo , utilisez les plugins capacitor au lieu des kits UI web uniquement comme Konsta UI : @capgo/capacitor-native-navigation --- une barre de navigation native, une barre de Liquid Glass sur iOS, et un style de barre de navigation flou sur Android. Votre routeur Next.js conserve l'état des routes ; le plugin possède la barre native de navigation.
@capgo/capacitor-transitions --- transitions de page à la manière d'Ionic et un retour en arrière par swipe sur l'édge sur iOS dans la couche WebView, sans adopter l'interface d'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 afin 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',
  },
});

Rendez une barre de Liquid Glass (iOS utilise la rendu système ; Android utilise un fond 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 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 cap-router-outlet, cap-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') context : fragment de texte HTML d'une chaîne de dialogue Capgo (clé parente `alternatives_cta_questions`). Page/zone : page de comparaison des alternatives de mise à jour en direct de Capacitor. Rôle : Paragraphe de marketing ou juridique long. Voir : page alternatives.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `alternatives_cta_questions` (Questions de CTA pour les alternatives). | Fragment de texte HTML d'une chaîne de dialogue Capgo (clé parente `appflow_cta_questions`). Page/zone : page de comparaison/migration de Appflow. Rôle : Paragraphe de marketing ou juridique long. Voir : page ionic-appflow.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `appflow_cta_questions` (Questions de CTA pour Appflow). | Fragment de texte HTML d'une chaîne de dialogue Capgo (clé parente `capwesome_cta_questions`). Page/zone : page de comparaison de Capawesome. Rôle : Paragraphe de marketing ou juridique long. Voir : page capwesome.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `capwesome_cta_questions` (Questions de CTA pour Capwesome). | Fragment de texte HTML d'une chaîne de dialogue Capgo (clé parente `consulting_faq_subtitle`). Page/zone : page de services de consultation. Rôle : Sujet de sous-titre ou de tagline. Voir : page consulting.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `consulting_faq_subtitle` (Sous-titre de FAQ pour les services de consultation). | Page/zone : page de comparaison/migration de Appflow. Rôle : Étiquette de navigation ou élément de navigation court. Voir : page ionic-appflow.astro, page ionic-enterprise-plugins.astro, page solutions/ionic-enterprise-plugins.astro. Clé de message `appflow_plugins_or` (Appflow Plugins ou). router.push() ou router.back()Ne dupliquez pas les en-têtes ou les pieds de page Web lorsqu'une navigation native contrôle ces surfaces.

Voir les guides complets : Utiliser @capgo/capacitor-navigation-native et Utiliser @capgo/capacitor-transitions.

Aires sûres avec Tailwind

Pour les zones sûres de l'appareil dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié comme tailwind-capacitor sur npm). Il fournit safe-areas des utilitaires et d'autres plugins de 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 outils tels que 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 un 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 ajuster seul le tag de vueport ne suffit généralement pas pour résoudre le problème. Travaillez à 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 à partir de app/layout.tsx:

import type { Viewport } from 'next';

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

Pages Router (pages/): insérer la balise de métadonnée de vueport dans pages/_app.tsxpas _document.tsx (Next.js n'applique peut-être pas les balises 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éer une coquille d'application unique et appliquer la mise en forme de l'espace sûr là-bas — pas dans plusieurs composants imbriqués :

Envelopper 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 répétée dans les en-têtes, les modales 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-capacitor, vous pouvez exprimer le même écran avec des utilitaires comme pt-safe pb-safe px-safe sur cette seule coquille.

Fixez Capacitor iOS `contentInset` à `never` contexte : Page/zone : Page de produit de mise à jour en direct. Rôle : Étiquette de navigation ou élément UI court. Clé de message `live_update_dynamic_label_to` (Étiquette dynamique de mise à jour en direct).

premier capacitor.config.tsDans contentInsetMode: 'css', préférez l'inset natif désactivé et laissez CSS (ou la navigation native)

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-*) Mélanger les écrans automatiques de contenu de __CAPGO_KEEP_0__ avec CSS

est une cause courante de double espace.

Trouvez l'élément qui déborde vraiment : 100vwTailwind w-screen, une largeur fixe en pixels, ou une min-width.

In le Web Inspector 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,
  }));

With Tailwind, remplacez w-screen avec w-full lorsque possible. De nombreux problèmes d'écoulement horizontal proviennent de 100vw / w-screen, une duplication de la marge de sécurité de l'aire sûre, ou un conteneur à largeur fixe — et non de la balise meta de la vue portative elle-même.

Optimisation de la Performance

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

Minimisez 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 initial.
Utilisez la mise en cache 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).
Leveragez les optimisations intégrées de Capacitor telles que la mise en 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
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)
Added une interface utilisateur ressemblant à celle des appareils natifs 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
Ajoutez plus de plugins natifs comme la Caméra, la géolocalisation ou les notifications push
Configurez les icônes et les écrans de démarrage pour la 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 en verre liquide et navigateur natif
Capacitor 8 Documentation
@capgo/capacitor-transitions — Transitions de page ressenties comme natives
@capgo/tailwind-capacitor — Utilitaires de zone sûre 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 à un compte gratuit aujourd'hui.

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

Si vous utilisez Convertissez votre application Next.js en iOS & Android avec Capacitor 8 pour planifier le travail du 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, Ajout ou mise à jour de plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, Alternatives de plugins Enterprise Ionic pour le flux de travail du produit dans Alternatives de plugins Enterprise Ionic, et Capgo Bâtiments natifs pour le flux de travail du produit dans Capgo Bâtiments natifs.

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