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 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
Construisez et testez sur les simulateurs iOS et Android
Activer 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 souhaitez commencer 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 de Capacitor

Code Reutilisation: Next.js vous permet d'écrire des composants réutilisables et de partager des code entre vos applications web et mobiles, ce qui vous permet de gagner du temps et d'effort en matière de développement.
Performance: Next.js offre des optimisations de performance intégrées, telles que le rendu côté serveur et le code en morceaux, ce qui garantit des temps de chargement rapides et une expérience utilisateur fluide.
Native Capabilities: Le Capacitor vous donne 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.
Simplified Development: Avec le 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é
Une application existante Next.js 15+ application
Xcode Xcode (pour le développement iOS, macOS uniquement)
Android Studio 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.tsfichier

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

module.exports = nextConfig;

fichier output: 'export' La mise en place indique à Next.js de générer des fichiers HTML statiques, et images: { unoptimized: true } Elle évite également 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 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.

La mise en place de Capacitor 8 dans 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ô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 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é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 plateformes natives :

bunx cap add ios
bunx cap add android

Capacitor créera ios et android dossiers au niveau de 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 Natives

Pour construire et déployer votre application mobile native, suivez ces étapes : Pour développer des applications iOS, vous devez avoir l' Xcode installé, et pour les applications Android, vous devez avoir l' 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 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

Lors du 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
```
On 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

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 temps réel ne s'applique qu'aux modifications web code.

Utiliser les Capacitor plugins

Les Capacitor plugins vous permettent d'accéder aux fonctionnalités du dispositif natif à partir de votre application Next.js. Explorons comment utiliser le Le plugin Partager comme exemple :

Installez le plugin Partager :

bun add @capacitor/share

Mettez à jour le pages/index.js fichier pour utiliser le plugin Partager :

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 « Partager 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 native avec __CAPGO_KEEP_1__ 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 justifié 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_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
@capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

— transitions de page Ionic et iOS edge swipe-back dans la couche WebView, sans adopter l’UI Ionic .

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

Configurez 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 de tabs en verre liquide (iOS utilise la mise en page système ; Android utilise un fond arrière 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 cap-router-outlet, cap-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') avant router.push() ou router.back(). N'ajoutez pas de titres de page web ou de pieds de page lorsqu'une navigation native possède ces surfaces.

Voir les guides complets : Utiliser @capgo/capacitor-navigation-native 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 paru sur __CAPGO_KEEP_0__ tailwind-capacitor qui fournit des utilitaires et d'autres plugins de Tailwind compatibles avec npm : safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

Utilisez des utilitaires comme styles/globals.css:

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

, et pt-safe, pb-safeau lieu de les répandre px-safe et env(safe-area-inset-*) à la main. Le projet est actuellement développé — si quelque chose manque pour votre configuration Next.js, ouvrir 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 scrollable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster seul le tag de vueport ne suffit généralement pas. Travaillez à travers ces vérifications dans l'ordre.

Assurez-vous que le tag de métadonnée 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 de métadonnée de vueport dans pages/_app.tsx, pas _document.tsx Les balises (Next.js) ne s'appliquent peut-être pas comme vous le souhaitez pour le comportement de la vue. _document.tsx Gérez l'espace sûr d'iOS à partir d'un seul enveloppe racine.

Créez une coquille d'application unique et appliquez-y le padding de l'espace sûr là, et non 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);
}

Le padding de l'espace sûr dupliqué dans les en-têtes, les modales et les enveloppes de disposition peut rendre 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 Fixez __CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` context : Page/zone : Page de produits en temps réel. Rôle : Étiquette de l'interface utilisateur courte ou élément de navigation. Clé de message `live_update_dynamic_label_to` (Étiquette dynamique de mise à jour en direct vers). `never` premier

En capacitor.config.ts, préférez l'insérer nativement désactivé et laissez CSS (ou la navigation native) gérer l'espace sûr : contentInsetMode: 'css'Mélanger les __CAPGO_KEEP_0__ automatiques d'insérer le contenu 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 large w-screenDans l'inspecteur Web 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,
  }));

In Safari Web Inspector, run: avec Safari, exécutez dans l'inspecteur Web : w-screen avec w-full lorsque cela est possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screenune mise en page de zone de sécurité dupliquée, ou d'un conteneur de largeur fixe — et non 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 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 la performance de chargement initiale.
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 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 :

Configurez Next.js pour l'export statique
Ajoutez Capacitor 8 avec des plugins essentiels
Construisez et déployez vers les simulateurs iOS et Android
Activez la rechargement en direct pour le développement
Résolvez les problèmes de mise en page iOS courants (vueport, zone de sécurité, débordement)
Ajoutez une interface utilisateur ressemblant à une application native avec Capgo Navigation et Transitions Native

Étapes suivantes :

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

Vous commencez un nouveau projet ? Consultez Construirez une application mobile Next.js à partir de zéro pour un guide détaillé.

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 ressenties comme natives
@capgo/tailwind-capacitor — Outils 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 inscrivez-vous à un compte gratuit aujourd'hui

Continuez avec 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 le détail d'implémentation dans Capacitor Plugins par Capgo Ajouter ou Mettre à Jour les Plugins pour le détail d'implémentation dans Ajouter ou Mettre à Jour les Plugins Alternatives aux Plugins Entreprise Ionic pour le flux de travail du produit dans Alternatives aux Plugins Entreprise Ionic, et Capgo Bâtiments Natives pour le flux de travail du produit dans Capgo Bâtiments Natives.

Convert Your Next.js App to iOS &amp; Android with Capacitor 8