Introduzione
Hai già un'applicazione web Nuxt? In questa guida imparerai come trasformarla in app mobile native per iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorate e nuove funzionalità.
Capacitor incapsula la tua web app in un container nativo, dandoti accesso alle API del dispositivo come fotocamera, filesystem e notifiche push, mantenendo il tuo codebase Vue esistente. A differenza di Flutter o React Native, non devi riscrivere nulla: il tuo code Nuxt funziona così com'è.
Cosa imparerai:
- Configura la tua app Nuxt esistente per la generazione statica
- Aggiungere Capacitor 8 con i plugin nativi essenziali
- Build e test sui simulatori iOS e Android
- Abilitare il live reload per uno sviluppo più rapido
- Risolvere i problemi di layout comuni su iOS (viewport, safe area, overflow orizzontale)
- Aggiungere una UI dall'aspetto nativo con Capgo Native Navigation and Transitions
Vuoi iniziare un nuovo progetto da zero? Dai un'occhiata alla nostra guida su Creare un'app mobile Nuxt da zero.
I vantaggi di Nuxt e Capacitor
- Riutilizzabilità di Code: Condividi i tuoi componenti Vue e la logica tra app web e mobile.
- Prestazioni: La generazione statica di Nuxt crea bundle ottimizzati perfetti per il mobile.
- Capacità native: Accedi a funzionalità del dispositivo come fotocamera, geolocalizzazione e filesystem tramite i plugin Capacitor.
- Sviluppo semplificato: Usa i pattern Vue/Nuxt familiari senza dover imparare lo sviluppo nativo.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- Un progetto Nuxt 4 applicazione
- Xcode (per lo sviluppo iOS, solo macOS)
- Android Studio (per lo sviluppo Android)
Configurare la tua app Nuxt per il mobile
Il primo passo è configurare la tua app Nuxt per la generazione statica. Capacitor ha bisogno di file HTML/JS/CSS statici per creare il bundle dell'app nativa.
Assicurati che la tua package.json abbia lo script generate:
{
"scripts": {
"dev": "nuxt dev",
"build": "nuxt build",
"generate": "nuxt generate",
"preview": "nuxt preview",
"mobile": "bun run generate && bunx cap sync",
"mobile:ios": "bun run mobile && bunx cap open ios",
"mobile:android": "bun run mobile && bunx cap open android"
}
}
Importante: Se utilizzi funzionalità lato server (rotte API, middleware lato server, ecc.), dovrai rifattorizzarle utilizzando alternative lato client o API esterne.
Testa la generazione statica eseguendo:
bun run generate
Dovresti vedere una .output/public cartella con i file statici. Questo è ciò che Capacitor includerà nella tua app nativa.
Aggiungere Capacitor 8 al tuo progetto
Per impacchettare la tua app Nuxt in un container 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 probabilmente ti serviranno:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences
Questi plugin offrono funzionalità essenziali:
- @capacitor/app: Gestisci gli eventi del ciclo di vita dell'app (foreground/background, deep link)
- @capacitor/keyboard: Controllo del comportamento della tastiera su mobile
- @capacitor/splash-screen: Gestione della splash screen nativa
- @capacitor/status-bar: Personalizza la status bar del dispositivo
- @capacitor/preferences: Storage key-value (come localStorage, ma nativo)
- Inizializza Capacitor con i dettagli del progetto:
bunx cap init my-app com.example.myapp --web-dir .output/public
Sostituisci my-app con il nome della tua app e com.example.myapp con il tuo 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: '.output/public',
plugins: {
SplashScreen: {
launchShowDuration: 2000,
launchAutoHide: true,
androidScaleType: 'CENTER_CROP',
splashFullScreen: true,
splashImmersive: true,
},
Keyboard: {
resize: 'body',
resizeOnFullScreen: true,
},
StatusBar: {
style: 'dark',
},
},
};
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 android
Capacitor creerà le ios e android cartelle nella root del tuo progetto contenenti 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 mobile
Questo esegue il tuo script personalizzato che genera la build statica di Nuxt e sincronizza i file con le piattaforme native.
Build e deployment di app native
Per buildare e distribuire la tua app mobile nativa, segui questi passaggi:
Per sviluppare app iOS, devi avere Xcode installato, mentre per le app Android devi avere 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:ios
Per Android:
bun run mobile:android
Oppure direttamente con Capacitor CLI:
bunx cap open ios
bunx cap open android
- Build e avvia l'app:

- In Android Studio, attendi che il progetto sia pronto, quindi clicca sul pulsante “Run” per distribuire l'app su un dispositivo connesso o un emulatore.

- In Xcode, configura il tuo account di firma 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 pulsante “Play” per avviare l'app sul dispositivo connesso.
Congratulazioni! Hai distribuito con successo la tua web app Nuxt su un dispositivo mobile.
Ma aspetta, c'è anche un modo più veloce per farlo durante lo sviluppo...
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: '.output/public',
server: {
url: 'http://YOUR_IP_ADDRESS:3000',
cleartext: true,
},
plugins: {
// ... your plugin config
},
};
export default config;
Sostituisci YOUR_IP_ADDRESS con il tuo indirizzo IP locale (es. 192.168.1.100).
- Applica le modifiche al tuo progetto nativo:
bunx cap copy
Il copy il comando copia la cartella web e le modifiche di configurazione nel progetto nativo senza aggiornare l'intero progetto.
- Avvia il server dev di Nuxt e ricostruisci in Xcode/Android Studio:
bun run dev
Ora, ogni volta che apporti modifiche alla tua app Nuxt, 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 web code.
Utilizzo dei plugin Capacitor
I plugin di Capacitor ti permettono di accedere alle funzionalità native del dispositivo dalla tua app Nuxt. Vediamo come usare Plugin di condivisione come esempio:
- Installa il plugin Share:
bun add @capacitor/share
- Crea o aggiorna una pagina per usare il plugin Share. In Nuxt 4, le pagine si trovano in
app/pages/:
<template>
<div class="p-6">
<h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
<button
@click="shareContent"
class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
>
Share now!
</button>
</div>
</template>
<script setup lang="ts">
import { Share } from '@capacitor/share';
async function shareContent() {
await Share.share({
title: 'Check this out!',
text: 'Built with Nuxt and Capacitor',
url: 'https://capacitorjs.com',
dialogTitle: 'Share with friends',
});
}
</script>
- Sincronizza le modifiche con il progetto nativo:
bun run mobile
Oppure sincronizza senza rebuild:
bunx cap sync
- Esegui il rebuild e avvia l'app sul tuo dispositivo.
Ora, quando clicchi sul pulsante “Share now!”, apparirà il dialog nativo di condivisione.
Successivamente, puoi rendere l'app più nativa su iOS e Android con navigazione e transizioni Capgo, e risolvere i comuni problemi di layout su iOS che causano overflow orizzontale o safe area tagliate.
UI dall'aspetto nativo con Capgo Native Navigation and Transitions
Ho lavorato per anni con Ionic per creare applicazioni cross-platform, ma integrarlo con Nuxt è un workaround e raramente vale la pena se hai già Tailwind CSS.
Per un'esperienza mobile nativa in un'app Nuxt + Capacitor, usa i plugin Capgo invece di UI kit solo web come Konsta UI:
- @capgo/capacitor-native-navigation — navbar nativa, tab bar Liquid Glass su iOS e stile tab bar sfocato su Android. Il router di Nuxt gestisce lo stato delle route; il plugin gestisce la chrome nativa.
- @capgo/capacitor-transitions — transizioni di pagina in stile Ionic e swipe-back dal bordo su iOS nel layer WebView, senza adottare Ionic UI.
Installa entrambi:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync
Configura 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 nell'app shell:
<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';
initTransitions({ platform: 'auto' });
const router = useRouter();
const outletRef = ref(null);
onMounted(() => {
if (outletRef.value) {
setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
}
});
const openSettings = () => {
setDirection('forward');
router.push('/settings');
};
</script>
<template>
<cap-router-outlet ref="outletRef">
<router-view />
</cap-router-outlet>
</template>
Avvolgi le pagine del router in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') oppure setDirection('back') prima di navigare. Non duplicare header o footer web quando la navigazione nativa gestisce quelle superfici.
Guarda le guide complete: Usando @capgo/capacitor-native-navigation e Uso di @capgo/capacitor-transitions.
Safe areas con Tailwind
Per le safe area dei dispositivi in Tailwind CSS, usa @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Offre safe-areas utility e altri plugin Tailwind compatibili con Capacitor:
bun add -D tailwind-capacitor
In app/assets/css/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";
Per Nuxt 4 con Tailwind CSS 4, mantieni questo import nel file CSS referenziato da nuxt.config.ts.
Usa utility come pt-safe, pb-safe, e px-safe invece di sparpagliare env(safe-area-inset-*) manualmente. Il progetto è in sviluppo attivo: se manca qualcosa per la tua configurazione Nuxt, apri una PR su GitHub.
Risolvere problemi di layout su iOS (Viewport, Safe Area e overflow orizzontale)
Se i contenuti appaiono tagliati, spostati o con scroll orizzontale su iOS, aggiungere più overflow-x: hidden o modificare il tag viewport di solito non basta. Segui questi controlli in ordine.
Assicurati che il meta tag viewport sia applicato correttamente
In nuxt.config.ts, imposta il viewport tramite app.head:
export default defineNuxtConfig({
app: {
head: {
meta: [
{
name: 'viewport',
content: 'width=device-width, initial-scale=1, viewport-fit=cover',
},
],
},
},
});
Gestisci la safe area di iOS da un unico wrapper root
Crea un unico app shell e applica lì il padding per la safe area — non in più componenti annidati:
html,
body,
#__nuxt {
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 in .app-shell. Il padding della safe-area duplicato in header, modal e wrapper del layout spesso fa apparire l'interfaccia tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi applicare lo stesso padding con utility come pt-safe pb-safe px-safe su quella singola shell.
Imposta Capacitor iOS contentInset a never per primo
In capacitor.config.ts, preferisci disabilitare i native inset e lascia che il CSS (o quella contentInsetMode: 'css'di Native Navigation) 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 CSS env(safe-area-inset-*) il padding è 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."
Conclusione
Hai convertito con successo la tua applicazione web Nuxt esistente in app native per iOS e Android usando Capacitor 8. Il tuo codebase Vue ora gira nativamente sui dispositivi mobili con accesso alle API del dispositivo.
Cosa hai realizzato:
- Configurato Nuxt per la generazione statica
- Aggiunto Capacitor 8 con i plugin essenziali
- Compilato e distribuito su simulatori iOS e Android
- Abilitato il live reload per lo sviluppo
- Corretti i problemi di layout comuni su iOS (viewport, safe area, overflow)
- Aggiunta un'UI dal tocco nativo con Capgo Native Navigation e Transitions
Prossimi passi:
- Configurazione Capgo per aggiornamenti over-the-air senza nuova sottomissione all'app store
- Aggiungi altri plugin nativi come Camera, Geolocation o Push Notifications
- Configura icone dell'app e splash screen per la produzione
- Prepara la tua app per l'invio su App Store e Google Play
Vuoi iniziare un nuovo progetto? Dai un'occhiata a Creare un'app mobile Nuxt da zero per una guida passo dopo passo.
Risorse
- Documentazione Nuxt
- Documentazione di Capacitor 8
- @capgo/capacitor-native-navigation — tab bar Liquid Glass e chrome nativo
- @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.
Continua da Converti la tua app Nuxt per iOS e Android con Capacitor 8
Se stai usando Converti la tua app Nuxt in iOS e Android con Capacitor 8 per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli sull'implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow di prodotto in Capgo Native Builds.