Introduzione
Hai una applicazione web Next.js esistente? In questo guide, imparerai a trasformarla in app mobili native iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorate e nuove funzionalità.
Capacitor avvolge la tua app web in un contenitore nativo, dando accesso a API come la telecamera, il filesystem e le notifiche push mentre mantiene il tuo codice React esistente. A differenza di React Native, non hai bisogno di ricodificare nulla — il tuo Next.js code funziona come sempre.
Ciò che imparerai:
- Configura la tua app Next.js esistente per l'esportazione statica
- Aggiungi Capacitor 8 con plugin nativi essenziali
- Costruisci e testa sui simulatori iOS e Android
- Abilita il reload live per un sviluppo più veloce
- Rendi comuni gli errori di layout iOS (viewport, area sicura, overflow orizzontale)
- Aggiungi un'interfaccia utente che sembra nativa con Capgo Native Navigation e Transitions
Se desideri iniziare un nuovo progetto da zero? Consulta la nostra guida su Creare un'app mobile Next.js da zero.
I benefici dell'uso di Next.js e Capacitor
- La reusabilità di Code: Next.js consente di scrivere componenti riutilizzabili e condividere code tra le tue app web e mobili, risparmiando tempo e sforzo di sviluppo.
- Performance: Next.js offre ottimizzazioni di prestazioni integrate, come la rendering server-side e code di split, garantendo tempi di caricamento veloci e un'esperienza utente liscia.
- Funzionalità native: Capacitor fornisce accesso alle funzionalità di dispositivo nativo come la fotocamera, la geolocalizzazione e altro, consentendo di creare app mobili ricche di funzionalità.
- Sviluppo semplificato: Con Capacitor, puoi sviluppare e testare la tua app mobile utilizzando tecnologie web familiari, riducendo la curva di apprendimento e semplificando il processo di sviluppo.
Requisiti preliminari
Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- Un'app esistente Configura Next.js 15+ l'applicazione
- Xcode (per lo sviluppo di iOS, disponibile solo su macOS)
- Android Studio (per lo sviluppo di Android)
Configurazione della tua App Next.js per dispositivi mobili
Il primo passo è configurare la tua app Next.js per l'esportazione statica. Capacitor richiede file HTML/JS/CSS statici per poterli bundle nella app nativa.
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;The output: 'export' Imposta che indica a Next.js di generare file HTML statici, e images: { unoptimized: true } salta l'ottimizzazione delle immagini di Next.js che richiede un server.
Importante: Se stai utilizzando funzionalità che richiedono un server (API percorsi, componenti server con fetching dei dati, ecc.), dovrai rifare quelle per utilizzare 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 buildDovresti 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 plugin Capacitor comuni che probabilmente avrai bisogno:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesQuesti plugin forniscono funzionalità essenziali:
- @capacitor/appGestisci gli eventi di ciclo di vita dell'applicazione (in primo piano/ in background, URL)
- @capacitor/keyboardControlla il comportamento della tastiera su dispositivi mobili
- @capacitor/splash-screenGestisci lo schermo di benvenuto nativo
- @capacitor/preferencesMemorizza dati chiave-valore persistentemente
- Inizializza Capacitor con i dettagli del tuo progetto:
bunx cap init my-app com.example.myapp --web-dir outSostituisci my-app con il nome della tua app e com.example.myapp con il tuo ID dell'applicazione (notazione di dominio inverso).
- Crea o aggiorna il
capacitor.config.tsfile 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 androidCapacitor creerà ios e android cartelle alla radice del tuo progetto contenenti i progetti nativi.
Per 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 mobileEsegue 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, devi iscriverti al programma di sviluppatore Apple per iOS e al Google Play Console per Android.
- Apri i progetti nativi:
Per iOS:
bun run mobile:iosPer Android:
bun run mobile:androidO direttamente con Capacitor CLI:
bunx cap open ios
bunx cap open android- Costruisci e esegui l'app:
-
In Android Studio, attendi che il progetto sia pronto, e poi clicca sul pulsante “Esegui” per distribuire l'app su un dispositivo o emulatore collegato.
-
In Xcode, configura il tuo account di firma per distribuire l'app su un dispositivo reale. Se non hai fatto ciò prima, Xcode ti guiderà attraverso il processo (nota che devi essere iscritto al programma sviluppatore Apple). Una volta configurato, clicca sul pulsante “Gioca” per eseguire l'app sul tuo dispositivo collegato.
Congratulazioni! Hai con successo distribuito la tua app web Next.js su un dispositivo mobile.
Capacitor Live Reload
Durante lo sviluppo, puoi sfruttare il live reloading per vedere i cambiamenti istantaneamente sul tuo dispositivo mobile. Per abilitare questa funzionalità, segui questi passaggi:
- Trovare l'indirizzo IP locale:
-
On macOS, esegui il seguente comando nel terminale:
ipconfig getifaddr en0 -
Esegui su Windows:
ipconfigCerca l'indirizzo IPv4 nell'output.
- Aggiorna il tuo
capacitor.config.tsper 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 copyIl copy comando copia la cartella 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 al tuo app Next.js, l'app mobile si ricaricherà automaticamente per riflettere quelle modifiche.
Nota: se installi nuovi plugin o apporti modifiche a file nativi, dovrai riavviare il progetto nativo poiché la ricarica in tempo reale si applica solo alle modifiche web code.
Usando Capacitor Plugin
I plugin Capacitor consentono di accedere alle funzionalità di dispositivo nativo dal tuo'app Next.js. Esploriamo come utilizzare il Plugin di condivisione come esempio:
- Installa il Plugin di condivisione:
bun add @capacitor/share- Aggiorna il
pages/index.jsfile per utilizzare il Plugin di condivisione:
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>
);
}- Sincronizza i cambiamenti con il progetto nativo:
Come 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 mobileOra, 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, consentendo di condividere il contenuto con altre app.
Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Next.js è un processo complicato e raramente vale la pena quando già hai Tailwind CSS 4.
Per un aspetto mobile nativo in un'app Next.js + Capacitor utilizza i Capgo plugin al posto di kit UI web come Konsta UI:
- @capgo/capacitor-navigazione-nativa — barra di navigazione nativa, Liquid Glass bar delle schede su iOS, e uno stile di barra delle schede sfocato 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 utente di Ionic.
Installa entrambi:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con il modello CSS inset per far rispettare il contenuto web le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Rendi una barra di tab di vetro liquido (iOS utilizza la rendering di proprietà del sistema; Android utilizza un sfondo WebView sfocato):
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 le 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 routing in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima router.push() o router.back(). Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede quelle superfici.
Vedi le guide complete: Utilizza @capgo/capacitor-navigazione-nativa E e @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transizioni Using @capgo/capacitor-transitions.
Per aree sicure del dispositivo in Tailwind CSS, utilizza
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor su __CAPGO_KEEP_0__). Offre tailwind-capacitor utilità e altri plugin Tailwind amichevoli con npm: safe-areas utilities and other Capacitor-friendly Tailwind plugins:
bun add -D tailwind-capacitorUtilizza utilità come styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";, e pt-safe, pb-safeal posto di spargere px-safe queste utilità env(safe-area-inset-*) in modo manuale. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Next.js, apri una PR su GitHub.
Risolvere Problemi di Layout iOS (Viewport, Area di Sicurezza e Flusso Orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere ulteriori overflow-x: hidden o modificare solo la tag di viewport di solito non risolve il problema. Passa attraverso questi controlli in ordine.
Assicurati che la tag meta viewport sia applicata correttamente
App Router (app/): esporta viewport da app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};Pages Router (pages/): metti la tag meta viewport in pages/_app.tsxnon _document.tsx (Next.js potrebbe non applicare le etichette come si aspetta per il comportamento del viewport). _document.tsx Gestisci l'area sicura di iOS da un unico wrapper radice.
Crea un unico contenitore dell'applicazione e applica il padding dell'area sicura lì — non nei componenti nidificati multipli:
Avvolgi tutta la contentazione della pagina dentro
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);
}. Il padding dell'area sicura duplicato nei titoli, 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-capacitorsu quel singolo contenitore. pt-safe pb-safe px-safe Imposta __CAPGO_KEEP_0__ iOS
Set Capacitor iOS contentInset to never Inizia con
In capacitor.config.tspreferisci l'inserimento nativo disabilitato e lascia che CSS (o la navigazione nativa) gestisca l'area sicura: contentInsetMode: 'css'Mescolare l'inserimento automatico del contenuto di __CAPGO_KEEP_0__ con 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-*) Trovare l'elemento che sta veramente sovraffollando
L'elemento solito colpevole è un elemento che utilizza
, Tailwind 100vw, una larghezza di pixel fissata, o un grande w-screenIn Safari Web Inspector, esegui: min-width.
Con Tailwind, sostituisci
[...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,
}));preferisci l'inserimento nativo disabilitato e lascia che CSS (o la navigazione nativa) gestisca l'area sicura: w-screen With w-full quando possibile. Molti problemi di sovrapposizione orizzontale derivano da 100vw / w-screen, padding di area sicura duplicato, o da un contenitore di larghezza fissata — non dal tag meta viewport stesso.
Optimizzazione delle Prestazioni
Per garantire prestazioni ottimali del tuo app Next.js e Capacitor, considera le seguenti best practice:
- 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).
- Sfrutta le ottimizzazioni integrate di Capacitor, come caching del view web e app bundling.
Conclusione
Hai convertito con successo la tua app web Next.js esistente in app native iOS e Android utilizzando Capacitor 8. Il tuo codice web ora funziona nativamente sui dispositivi mobili con accesso alle API dei dispositivi.
Cosa hai realizzato:
- 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 il development
- Risolto problemi di layout iOS comuni (viewport, area sicura, overflow)
- Aggiunto UI con aspetto nativo con Capgo Native Navigation e Transizioni
Passaggi successivi:
- Configura Capgo per aggiornamenti senza app store senza riconvalidazione
- Aggiungi plugin nativi aggiuntivi come Camera, Geolocalizzazione o Notifiche Push
- Configura icone dell'app e schermate di avvio per la produzione
- Prepara la tua app per la presentazione su App Store e Google Play
Stai iniziando un nuovo progetto? Controlla Crea un'app Mobile Next.js da zero per una guida passo passo.
Risorse
- Documentazione Next.js
- @Capgo/capgo/capacitor-native-navigation — Liquid Glass barra dei tasti e chrome nativo
- Capacitor 8 Documentazione
- @Capgo/capgo/capacitor-transitions — transizioni di pagina con un sentimento nativo
- @capgo/tailwind-capacitor — Strumenti di area sicura di Tailwind per Capacitor
- Capgo - Aggiornamenti in tempo reale per App Capacitor
Impara come Capgo possa aiutarti a costruire app migliori in modo più veloce, iscrivi un account gratuito 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, Plugins da Capacitor sviluppati da Capgo per i dettagli di implementazione in Plugins da Capacitor sviluppati da Capgo, Aggiunta o Aggiornamento di Plugins per i dettagli di implementazione in Aggiunta o Aggiornamento di Plugins, Alternative per Plugin Enterprise di Ionic per il workflow del prodotto in Alternative per Plugin Enterprise di Ionic, e Capgo Build Native per il workflow del prodotto in Capgo Build Native.
