Converti la tua app Next.js in iOS & Android con Capacitor 8

Introduzione

Hai già un'applicazione web Next.js? In questo guide, imparerai a trasformarla in applicazioni mobili native per iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorata e nuove funzionalità.

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.

Ciò che imparerai:

Configura la tua app Next.js esistente per l'esportazione statica
Add Capacitor 8 with essential native plugins
Costruisci e testa su simulatori iOS e Android
Abilita il reload live per un sviluppo più veloce
Correggi problemi di layout comuni su iOS (viewport, area sicura, overflow orizzontale)
Add native-feeling UI with Capgo Native Navigation and Transitions

Se desideri iniziare un nuovo progetto da zero? Costruire un'app mobile Next.js da zero.

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.
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.
Funzionalità native: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
Sviluppo semplificato: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

Prerequisiti

Prima di iniziare, assicurati di avere:

Node.js 18+ installato
Un'applicazione Next.js esistente Next.js 15+ Xcode
(solo per lo sviluppo di iOS su macOS) Android Studio
(solo per lo sviluppo di Android) Configurazione dell'applicazione Next.js per dispositivi mobili

Il primo passo è configurare l'applicazione Next.js per l'esportazione statica. __CAPGO_KEEP_0__ richiede file HTML/JS/CSS statici per poterli bundle nel'app nativa.

The first step is to configure your Next.js app for static export. Capacitor needs static HTML/JS/CSS files to bundle into the native app.

Apri il tuo next.config.js (o next.config.ts) file e aggiungi la configurazione di esportazione:

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

module.exports = nextConfig;

Il output: 'export' impostazione dice a Next.js di generare file HTML statici, e images: { unoptimized: true } evita l'ottimizzazione delle immagini di Next.js che richiede un server.

Importante: Se stai utilizzando funzionalità che richiedono un server (ad esempio API percorsi, componenti server con fetching dei dati, ecc.), dovrai rifare quelle utilizzando alternative client-side o API esterne.

Aggiungi script specifici per dispositivi mobili al tuo 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"
  }
}

Testa l'esportazione statica eseguendo:

bun run build

Devi vedere un out cartella alla radice del tuo progetto. Questo contiene tutti i file statici che Capacitor compilerà nel tuo app nativo.

Aggiungere Capacitor 8 al tuo progetto

Per pacchettizzare la tua app Next.js in un contenitore mobile nativo, segui questi passaggi:

Installa Capacitor core e CLI:

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

Installa i plugin Capacitor comuni che ti serviranno probabilmente:

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

Questi plugin forniscono funzionalità essenziali:

@capacitor/app: Gestisci gli eventi di ciclo di vita dell'applicazione (in primo piano/ in background, URL)
@capacitor/keyboard: Controlla il comportamento del tastierino su mobile
@capacitor/splash-screen: Gestisci lo schermo di benvenuto nativo
@capacitor/preferences: Salva dati chiave-valore persistentemente

Inizia Capacitor con i dettagli del tuo progetto:

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

Sostituisci my-app con il nome del tuo app e com.example.myapp con l'ID del tuo app (notazione di dominio inverso).

Crea o aggiorna il capacitor.config.ts file con la configurazione corretta:

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;

Installa piattaforme native:

bun add @capacitor/ios @capacitor/android

Aggiungi le cartelle delle piattaforme native:

bunx cap add ios
bunx cap add android

Capacitor creerà ios e android context: Pagina/Area: Sito web di marketing di Capgo. Ruolo: Etichetta breve UI o elemento di navigazione. Visto in: pagina trust.astro. Chiave messaggio `e` (E).

To costruire il progetto Android, hai bisogno di Android Studio. Per iOS, hai bisogno di un Mac con Xcode.

Costruisci e sincronizza il tuo progetto:

bun run mobile

Questo esegue il tuo script personalizzato che costruisce il progetto Next.js e sincronizza i file statici con le piattaforme native.

Costruire e Distribuire Applicazioni Native

Per costruire e distribuire la tua applicazione mobile nativa, segui questi passaggi: Per sviluppare app iOS, hai bisogno di avere Xcode installato, e per le app Android, hai bisogno di avere Android Studio installato. Inoltre, se hai l'intenzione di distribuire la tua app sul negozio di app, hai bisogno di iscriverti al programma di sviluppatore Apple per iOS e al Google Play Console per Android.

Avvia i progetti nativi:

Per iOS:

bun run mobile:ios

Per Android:

bun run mobile:android

O direttamente con Capacitor CLI:

bunx cap open ios
bunx cap open android

Costruisci e esegui l'app:

android-studio-run

In Android Studio, attendi che il progetto sia pronto e poi clicca sul pulsante "Esegui" per distribuire l'app su un dispositivo connesso o emulatore.
In Xcode, configura il tuo account di firma per distribuire l'app su un dispositivo reale. Se non l'hai fatto prima, Xcode ti guiderà attraverso il processo (nota che devi essere iscritto al Apple Developer Program). Una volta configurato, clicca sul pulsante "Gioca" per eseguire l'app sul tuo dispositivo connesso.

Congratulazioni! Hai con successo distribuito la tua app web Next.js su un dispositivo mobile.

Ma aspetta, c'è anche un modo più veloce per farlo durante lo sviluppo...

Capacitor Live Reload

Esegui il riavvio in tempo reale durante lo sviluppo per visualizzare le modifiche istantaneamente sul tuo dispositivo mobile. Per attivare questa funzionalità, segui questi passaggi:

Cerca l'indirizzo IP locale:

Sui sistemi macOS, esegui il seguente comando nel terminale:
```
ipconfig getifaddr en0
```
Sui sistemi Windows, esegui:
```
ipconfig
```
Cerca l'indirizzo IPv4 nell'output.

Aggiorna il tuo capacitor.config.ts a puntare al tuo server di sviluppo:

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;

Sostituisci YOUR_IP_ADDRESS con l'indirizzo IP locale (ad esempio, 192.168.1.100).

Applica le modifiche al tuo progetto nativo:

bunx cap copy

Il copy La riga di comando copia il folder web e le modifiche di configurazione nel progetto nativo senza aggiornare l'intero progetto.

Riavvia e esegui l'app sul tuo dispositivo utilizzando Android Studio o Xcode.

Ora, ogni volta che apporti modifiche all'app Next.js, l'app mobile si ricaricherà automaticamente per riflettere quelle modifiche.

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.

Utilizzo dei plugin Capacitor

Capacitor plugin consentono di accedere alle funzionalità del dispositivo nativo dall'app Next.js. Esploriamo come utilizzare il plugin di condivisione come esempio: Installa il plugin di condivisione: Aggiorna il file per utilizzare il plugin di condivisione:

Sincronizza le modifiche con il progetto nativo:

bun add @capacitor/share

Aggiorna il file per utilizzare il plugin di condivisione: pages/index.js Sincronizza le modifiche con il progetto nativo:

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

Installa il plugin di condivisione:

As menzionato in precedenza, quando si installano nuovi plugin, è necessario eseguire un'operazione di sincronizzazione e poi ri-deployare l'app sul dispositivo. Per farlo, esegui il seguente comando:

bun run mobile

Ora, sincronizza senza ricostruire:

bunx cap sync

Ricostruisci e esegui l'app sul tuo dispositivo.

Ora, quando clicchi sul pulsante “Condividi ora!”, apparirà il dialogo di condivisione nativo, che ti consente di condividere il contenuto con altre app.

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

## Interfaccia utente con un aspetto nativo con __CAPGO_KEEP_1__ Navigazione e transizioni native L'ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Next.js è un po' complicato e raramente vale la pena quando già hai.

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

Per un aspetto mobile nativo in un'app Next.js + capgo, utilizza capacitor plugin al posto di kit di interfaccia utente web come Konsta UI: @capgo/capacitor-navigazione-nativa --- barra di navigazione nativa, Liquid Glass tab bar su iOS e uno stile di barra tab con sfocatura su Android. Il tuo router Next.js mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
@capgo/capacitor-transizioni --- transizioni di pagina dello stile Ionic e swipe-back di iOS nell' layer WebView, senza adottare l'interfaccia UI di Ionic.

Installate sia:

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

Configura la navigazione nativa con il CSS inset mode affinché il contenuto web rispetti le barre native:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendi una barra tab di vetro liquido (iOS utilizza la rendering di sistema; Android utilizza un sfondo di WebView con sfocatura):

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

Aggiungi transizioni di pagina native nel contenitore dell'app:

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

Avvolgi le pagine di destinazione in cap-router-outlet, cap-pagee cap-contente chiama setDirection('forward') o setDirection('back') contexto: frammento di testo HTML da una stringa UI Capgo più lunga (chiave padre `alternatives_cta_questions`). Pagina/area: pagina di confronto delle alternative per Capacitor. Ruolo: paragrafo di marketing o legale lungo. Visto in: pagina alternatives.astro. Preserva i termini del prodotto e della marca Capgo esattamente. Chiave del messaggio `alternatives_cta_questions` (Domande per l'azione delle alternative). | Frammento di testo HTML da una stringa UI Capgo più lunga (chiave padre `appflow_cta_questions`). Pagina/area: pagina di confronto e migrazione di Appflow. Ruolo: paragrafo di marketing o legale lungo. Visto in: pagina ionic-appflow.astro. Preserva i termini del prodotto e della marca Capgo esattamente. Chiave del messaggio `appflow_cta_questions` (Domande per l'azione di Appflow). | Frammento di testo HTML da una stringa UI Capgo più lunga (chiave padre `capwesome_cta_questions`). Pagina/area: pagina di confronto di Capawesome. Ruolo: paragrafo di marketing o legale lungo. Visto in: pagina capwesome.astro. Preserva i termini del prodotto e della marca Capgo esattamente. Chiave del messaggio `capwesome_cta_questions` (Domande per l'azione di Capwesome). | Frammento di testo HTML da una stringa UI Capgo più lunga (chiave padre `consulting_faq_subtitle`). Pagina/area: pagina dei servizi di consulenza. Ruolo: sottotitolo o didascalia di sezione. Visto in: pagina consulting.astro. Preserva i termini del prodotto e della marca Capgo esattamente. Chiave del messaggio `consulting_faq_subtitle` (Sottotitolo FAQ dei servizi di consulenza). | Pagina/area: pagina di confronto e migrazione di Appflow. Ruolo: etichetta o elemento di navigazione breve. Visto in: pagina ionic-appflow.astro, pagina ionic-enterprise-plugins.astro, pagina soluzioni/ionic-enterprise-plugins.astro. Chiave del messaggio `appflow_plugins_or` (Appflow Plugins O). router.push() o router.back()Vedi le guide complete:

Usa @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigazione nativa Using @capgo/capacitor-native-navigation Usa @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transizioni Using @capgo/capacitor-transitions.

Per le aree sicure del dispositivo in Tailwind CSS, utilizza

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor Fornisce utilità e altri plugin di Tailwind compatibili con __CAPGO_KEEP_0__: tailwind-capacitor on npm). It provides safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

In styles/globals.css:

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

Utilizza strumenti come pt-safe, pb-safe, e px-safe piuttosto che aggiungerli env(safe-area-inset-*) manualmente. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Next.js, apri un PR su GitHub.

Risolvere problemi di layout su iOS (Viewport, Area di sicurezza e sovrapposizione orizzontale)

Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o modificare il tag viewport da solo non risolve di solito il problema. Esegui questi controlli in ordine.

Assicurati che il tag meta viewport sia applicato correttamente

Router dell'app (app/): esporta viewport Dal app/layout.tsx:

import type { Viewport } from 'next';

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

Router delle Pagine (pages/aggiungere l'etichetta meta del viewport in pages/_app.tsx, non _document.tsx (Next.js potrebbe non applicare le etichette dal modo in cui si aspetta per il comportamento del viewport). _document.tsx Gestisci l'area sicura di iOS da un wrapper radice solo

Crea un unico contenitore dell'applicazione e applica l'aggiustamento dell'area sicura lì — non in componenti nidificati multipli:

Avvolgi tutto il contenuto della pagina all'interno di

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

L'aggiustamento dell'area sicura duplicato nei capienti, nei modali e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande. .app-shellCon

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorEsprimere lo stesso padding con utilità come pt-safe pb-safe px-safe su quella singola shell.

Imposta Capacitor iOS `contentInset` a `never` context: Pagina/Area: Pagina prodotti di aggiornamenti in tempo reale. Ruolo: Etichetta di navigazione breve o elemento UI.

primo capacitor.config.tsIn contentInsetMode: 'css', preferisci l'inserimento nativo disabilitato e lascia che CSS (o la navigazione nativa)

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-*) Mescolare automaticamente l'inserimento di contenuto di __CAPGO_KEEP_0__ con CSS

è una causa comune di doppia spaziatura.

Trova l'elemento che sta veramente sovrascrivendo il contenuto. 100vwTailwind w-screen, una larghezza di pixel fissi, o una grande min-width.

In Safari Web Inspector, esegui:

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

Con Tailwind, sostituisci w-screen con w-full quando possibile. Molti problemi di sovrapposizione orizzontale derivano da 100vw / w-screen, sovrapposizione di padding di area sicura duplicata, o un contenitore di larghezza fissata — non dal tag meta viewport stesso.

Optimizzazione delle Prestazioni

Per garantire prestazioni ottimali per il tuo app Next.js e Capacitor, considera le seguenti pratiche di ottimizzazione:

Minimizza la dimensione dell'app rimuovendo le dipendenze e gli asset non utilizzati.
Optimizza le immagini e altri file multimediali per ridurre i tempi di caricamento.
Implementa il caricamento lazy per i componenti e le pagine per migliorare le prestazioni di caricamento iniziale.
Utilizza la rendering server-side (SSR) con Next.js per migliorare la velocità di caricamento dell'app e l'ottimizzazione per i motori di ricerca (SEO).
Leverage le ottimizzazioni integrate di Capacitor, come il caching della vista web e il bundle dell'app.

Conclusioni

Hai avuto successo nel convertire la tua applicazione web Next.js esistente in app native iOS e Android utilizzando Capacitor 8. Il tuo codice web ora funziona nativamente su dispositivi mobili con accesso alle API di dispositivo.

Cosa hai ottenuto:

Configurato Next.js per l'esportazione statica
Aggiunto Capacitor 8 con plugin essenziali
Costruito e distribuito su simulatori iOS e Android
Abilitato il reload live per lo sviluppo
Risolto problemi di layout iOS comuni (viewport, area sicura, overflow)
Aggiunto un'interfaccia utente che sembra nativa con Capgo Native Navigation e Transitions

Esegui i passaggi successivi:

Configura Capgo per aggiornamenti over-the-air senza riconferma dell'app store
Aggiungi più plugin nativi come Camera, Geolocalizzazione o Notifiche Push
Configura icone dell'app e schermate di avvio per la produzione
Prepara l'app per la pubblicazione su App Store e Google Play

Iniziando un nuovo progetto? Consulta Costruisci un'app mobile Next.js da zero per una guida passo dopo passo.

Risorse

Documentazione Next.js
@capgo/capacitor-navigazione nativa --- Barra di navigazione Liquida Glass e Chrome nativo
--- Capacitor 8 Documentazione
@capgo/capacitor-transizioni --- Transizioni di pagina con un sentore di natività
@capgo/tailwind-capacitor --- Utilità di area sicura di Tailwind per Capacitor
--- Capgo - Aggiornamenti in tempo reale per Applicazioni Capacitor

Scopri come Capgo possa aiutarti a creare applicazioni migliori in modo più veloce iscrivi oggi.

Continua da Converti la tua App Next.js in iOS & Android con Capacitor 8

Se stai utilizzando Converti la tua App Next.js in iOS & Android con Capacitor 8 per pianificare il lavoro dei plugin nativi, connettilo con Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin, Capacitor Plugin da Capgo per i dettagli di implementazione in Capacitor Plugin da Capgo Aggiungere o Aggiornare i Plugin per i dettagli di implementazione in Aggiungere o Aggiornare i Plugin, Alternative ai Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternative ai Plugin Enterprise Ionic, e Capgo Costruzioni Native per il flusso di lavoro del prodotto in Capgo Costruzioni Native.

Converti la tua App Next.js in iOS e Android con Capacitor 8