Introduzione
Hai già un'applicazione web in Next.js? In questa guida imparerai come trasformarla in app native per iOS e Android utilizzando Capacitor 8 — l'ultima versione con performance migliorate e nuove funzionalità.
Capacitor avvolge la tua web app in un container nativo, permettendoti di accedere alle API del dispositivo come fotocamera, filesystem e notifiche push, mantenendo intatto il tuo codebase React. A differenza di React Native, non devi riscrivere nulla: il tuo code Next.js funziona così com'è.
Cosa imparerai:
- Configurare la tua app Next.js per l'export statico
- Aggiungere Capacitor 8 con i plugin nativi essenziali
- Build e test su simulatori iOS e Android
- Abilitare la live reload per uno sviluppo più veloce
- Risolvere i comuni problemi di layout su iOS (viewport, safe area, overflow orizzontale)
- Aggiungere una UI nativa con Capgo Native Navigation and Transitions
Vuoi iniziare un nuovo progetto da zero? Consulta la nostra guida su Creare un'app mobile Next.js da zero.
Vantaggi di usare Next.js e Capacitor
- Riutilizzabilità con Code: Next.js ti permette di scrivere componenti riutilizzabili e condividere code tra le tue app web e mobile, risparmiando tempo e fatica nello sviluppo.
- Performance: Next.js offre ottimizzazioni delle performance integrate, come il server-side rendering e il code splitting, garantendo tempi di caricamento rapidi e un'esperienza utente fluida.
- Capacità Native: Capacitor permette di accedere alle funzionalità native del dispositivo, come la fotocamera e la geolocalizzazione, consentendoti di creare app mobile ricche di funzionalità.
- Sviluppo Semplificato: Con Capacitor, puoi sviluppare e testare la tua app mobile usando tecnologie web familiari, riducendo la curva di apprendimento e snellendo il processo di sviluppo.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- Un esistente Next.js 15+ applicazione
- Xcode (per lo sviluppo iOS, solo su macOS)
- Android Studio (per lo sviluppo Android)
Configurare la tua app Next.js per il mobile
Il primo passo è configurare la tua app Next.js per l'export statico. Capacitor richiede file HTML/JS/CSS statici per il bundle nell'app nativa.
Apri il tuo next.config.js (o next.config.ts) file e aggiungi la configurazione di export:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;L'oggetto output: 'export' l'impostazione dice 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 usi funzionalità che richiedono un server (API routes, server components con data fetching, ecc.), dovrai rifattorizzarle usando alternative client-side o API esterne.
Aggiungi gli script specifici per mobile 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'export statico eseguendo:
bun run buildDovresti vedere una cartella out nella root del progetto. Contiene tutti i file statici che Capacitor includerà nel tuo native app.
Aggiungi Capacitor 8 al tuo progetto
Per impacchettare la tua app Next.js in un container mobile nativo, segui questi passaggi:
- Installa il core di Capacitor e CLI:
bun add @capacitor/core
bun add -D @capacitor/cli- Installa i plugin Capacitor comuni che probabilmente ti serviranno:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesQuesti plugin offrono funzionalità essenziali:
- @capacitor/app: Gestione degli eventi del ciclo di vita dell'app (foreground/background, URL)
- @capacitor/keyboard: Controllo del comportamento della tastiera su mobile
- @capacitor/splash-screen: Gestione della splash screen nativa
- @capacitor/preferences: Salvataggio persistente di dati key-value
- Inizializza Capacitor con i dettagli del 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 l'app ID (notazione reverse domain).
- 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 le piattaforme native:
bun add @capacitor/ios @capacitor/android- Aggiungi le cartelle delle piattaforme native:
bunx cap add ios
bunx cap add androidCapacitor creerà le ios e android cartelle nella root del progetto con i progetti nativi.
Per buildare il progetto Android, ti serve Android Studio. Per iOS, serve un Mac con Xcode.
- Build e sync del progetto:
bun run mobileQuesto esegue il tuo script personalizzato che effettua il build del progetto Next.js e sincronizza i file statici con le piattaforme native.
Build e deploy di app native
Per buildare e deployare la tua app mobile nativa, segui questi passaggi: Per sviluppare app iOS, devi avere Xcode installato, mentre per le app Android ti serve Android Studio installato. Inoltre, se intendi distribuire la tua app sugli store, devi iscriverti all'Apple Developer Program per iOS e alla 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- Builda ed esegui l'app:
-
In Android Studio, attendi che il progetto sia pronto e clicca sul tasto “Run” per distribuire l'app su un dispositivo connesso o un emulatore.
-
In Xcode, configura il tuo account di signing per distribuire l'app su un dispositivo reale. Se non l'hai mai fatto, Xcode ti guiderà nel processo (nota che devi essere iscritto all'Apple Developer Program). Una volta configurato, clicca sul tasto “Play” per avviare l'app sul dispositivo connesso.
Complimenti! Hai distribuito con successo la tua web app Next.js su un dispositivo mobile.
Live Reload con Capacitor
Durante lo sviluppo, puoi sfruttare il live reloading per vedere le modifiche istantaneamente sul tuo dispositivo mobile. Per abilitare questa funzione, segui questi passaggi:
- Trova il tuo indirizzo IP locale:
-
Su macOS, esegui il seguente comando nel terminale:
ipconfig getifaddr en0 -
Su Windows, esegui:
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 il tuo indirizzo IP locale (es. 192.168.1.100).
- Applica le modifiche al progetto nativo:
bunx cap copyL'oggetto copy il comando copia la cartella web e le modifiche di configurazione nel progetto nativo senza aggiornare l'intero progetto.
- Ricompila e avvia l'app sul tuo dispositivo con Android Studio o Xcode.
Ora, ogni volta che modifichi la tua app Next.js, l'app mobile si ricaricherà automaticamente per riflettere le modifiche.
Nota: se installi nuovi plugin o modifichi file nativi, dovrai ricostruire il progetto nativo, poiché il live reloading si applica solo alle modifiche code web.
Utilizzo dei plugin Capacitor
I plugin di Capacitor ti permettono di accedere alle funzionalità native del dispositivo dalla tua app Next.js. Vediamo come usare il plugin Share come esempio:
- Installa il plugin Share:
bun add @capacitor/share- Aggiorna il file
pages/index.jsper usare il plugin Share:
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 le modifiche con il progetto nativo:
Come detto prima, quando installi nuovi plugin devi eseguire un'operazione di sync e poi ridistribuire l'app sul dispositivo. Per farlo, esegui questo comando:
bun run mobileOppure esegui solo il sync senza rebuild:
bunx cap sync- Fai il rebuild e avvia l'app sul tuo dispositivo.
Ora, quando clicchi sul pulsante “Share now!”, apparirà il dialog nativo di condivisione, che ti permette di condividere i contenuti con altre app.
Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarlo con Next.js è complicato e raramente ne vale la pena se hai già Tailwind CSS 4.
Per un feeling mobile nativo in un'app Next.js + Capacitor, usa i plugin Capgo invece di UI kit solo web come Konsta UI:
- @capgo/capacitor-native-navigation — navbar nativa, Liquid Glass tab bar su iOS e uno stile tab bar sfocato su Android. Il router di Next.js gestisce lo stato delle rotte; il plugin gestisce la UI nativa.
- @capgo/capacitor-transitions — transizioni di pagina in stile Ionic e swipe-back laterale su iOS nel layer WebView, senza adottare Ionic UI.
Installa entrambi:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con la modalità CSS inset, così il contenuto web rispetta le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Renderizza una tab bar Liquid Glass (iOS usa il rendering di sistema; Android usa un backdrop 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 transizioni di pagina native nel tuo app shell:
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });Avvolgi le pagine delle route in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima router.push() o router.back(). Non duplicare header o footer web quando la navigazione nativa gestisce quelle superfici.
Guarda le guide complete: Usare @capgo/capacitor-native-navigation e Usare @capgo/capacitor-transitions.
Safe areas con Tailwind
Per le safe area del dispositivo in Tailwind CSS, usa @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Fornisce safe-areas utility e altri plugin Tailwind compatibili con Capacitor:
bun add -D tailwind-capacitorIn styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Usa utility come pt-safe, pb-safe, e px-safe invece di spargere env(safe-area-inset-*) a mano. Il progetto è in fase di sviluppo attivo — se manca qualcosa per il tuo setup Next.js, apri una PR su GitHub.
Risolvere i problemi di layout su iOS (viewport, Safe Area e overflow orizzontale)
Se il contenuto appare tagliato, spostato o con scroll orizzontale su iOS, aggiungendo più overflow-x: hidden o modificare solo il tag viewport di solito non basta. Segui questi controlli in ordine.
Assicurati che il meta tag viewport sia applicato correttamente
App Router (app/): export viewport da app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};Pages Router (pages/): inserisci il meta tag viewport in pages/_app.tsx, non _document.tsx (Next.js potrebbe non applicare i tag da _document.tsx come ti aspetti per il comportamento del viewport).
Gestisci la safe area di iOS da un unico wrapper root
Crea un'unica app shell e applica lì il padding della safe area — non in più componenti annidati:
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);
}Racchiudi tutto il contenuto della pagina dentro .app-shell. Il padding della safe area duplicato in header, modal e layout wrapper spesso fa sembrare la UI tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi esprimere lo stesso padding con utility come pt-safe pb-safe px-safe su quell'unica shell.
Imposta Capacitor iOS contentInset a never first
In capacitor.config.ts, preferisci l'inset nativo disabilitato e lascia che il CSS (o la Native Navigation) contentInsetMode: 'css') gestisca la safe area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mescolare l'automatic content inset di Capacitor con il padding env(safe-area-inset-*) CSS è una causa comune di spaziature doppie.
Trova il vero elemento che causa l'overflow
Il colpevole di solito è un elemento che usa 100vw, Tailwind w-screen, una larghezza fissa in pixel, o un 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 overflow orizzontale derivano da 100vw / w-screen, padding della safe-area duplicato o un contenitore a larghezza fissa — non dal meta tag viewport stesso."
Ottimizzazione delle Performance
Per garantire performance ottimali alla tua app Next.js e Capacitor, considera queste best practice:
- Riduci la dimensione dell'app eliminando asset e dipendenze inutilizzate.
- Ottimizza immagini e altri file media per ridurre i tempi di caricamento.
- Implementa il lazy loading per componenti e pagine per migliorare il caricamento iniziale.
- Usa il server-side rendering (SSR) con Next.js per velocizzare l'app e migliorare la SEO.
- Sfrutta le ottimizzazioni integrate di Capacitor, come il caching della web view e l'app bundling.
Conclusione
Hai convertito con successo la tua web app Next.js in app native iOS e Android usando Capacitor 8. Il tuo codebase web ora gira nativamente su dispositivi mobile con accesso alle API del dispositivo.
Cosa hai realizzato:
- Configurato Next.js per l'export statico
- Aggiunto Capacitor 8 con i plugin essenziali
- Build e deploy su simulatori iOS e Android
- Abilitato il live reload per lo sviluppo
- Risolti i comuni problemi di layout iOS (viewport, safe area, overflow)
- Aggiunta una UI nativa con Capgo Native Navigation and Transitions
Prossimi passi:
- Configura Capgo per gli aggiornamenti over-the-air senza resubmission sugli store
- Aggiungi altri plugin nativi come Camera, Geolocation o Push Notifications
- Configura icone e splash screen per la produzione
- Prepara l'app per la pubblicazione su App Store e Google Play
Vuoi iniziare un nuovo progetto? Dai un'occhiata a Creare un'app mobile con Next.js da zero per una guida passo dopo passo.
Risorse
- Documentazione Next.js
- @capgo/capacitor-native-navigation — tab bar Liquid Glass e chrome nativo
- Documentazione Capacitor 8
- @capgo/capacitor-transitions — transizioni di pagina dall'aspetto nativo
- @capgo/tailwind-capacitor — Utility safe-area di Tailwind per Capacitor
- Capgo - Live Updates per app Capacitor
Scopri come Capgo può aiutarti a creare app migliori più velocemente, registrati per un account gratuito oggi stesso.
Continua da Converti la tua app Next.js in iOS & Android con Capacitor 8
Se stai usando Converti la tua app Next.js in iOS & Android con Capacitor 8 per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin Capgo per il workflow del prodotto nella Directory dei plugin Capgo, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins by Capgo, Aggiungere o aggiornare i plugin per i dettagli di implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow di prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow di prodotto in Capgo Native Builds.
