Converti la tua app Nuxt in iOS e Android con Capacitor 8

Introduzione

Hai già un'applicazione web Nuxt? In questa guida imparerai come trasformarla in app native iOS e Android usando 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 Vue. 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 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.

Vantaggi di Nuxt e Capacitor

Riutilizzabilità di Code: Condividi i tuoi componenti Vue e la logica tra web e app mobile.
Prestazioni: La generazione statica di Nuxt crea bundle ottimizzati, perfetti per il mobile.
Capacità native: Accedi alle funzionalità del dispositivo come camera, geolocalizzazione e filesystem tramite i plugin Capacitor.
Sviluppo semplificato: Usa i pattern Vue/Nuxt che già conosci, senza dover imparare lo sviluppo nativo.

Prerequisiti

Prima di iniziare, assicurati di avere:

Node.js 18+ installato
Un esistente 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.ts file 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:

android-studio-run

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.

xcode-run

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...

Capacitor Live Reload

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:
```
ipconfig
```
Cerca l'indirizzo IPv4 nell'output.

Aggiorna il tuo capacitor.config.ts per 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 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 fai il rebuild in Xcode/Android Studio:

bun run dev

Ora, ogni volta che apporterai modifiche alla tua app Nuxt, l'app mobile si ricaricherà automaticamente per rifletterle.

Nota: Se installi nuovi plugin o modifichi file nativi, dovrai rifare il build del 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.

Ho lavorato per anni con Ionic per creare app cross-platform, ma integrarlo con Nuxt è complicato e raramente ne vale la pena se hai già Tailwind CSS.

Per un feeling mobile nativo 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 sfocata su Android. Il router di Nuxt gestisce lo stato delle rotte; il plugin gestisce la UI 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') o setDirection('back') prima della navigazione. Non duplicare header o footer web quando la navigazione nativa gestisce quelle aree.

Guarda le guide complete: Usando @capgo/capacitor-native-navigation e Uso di @capgo/capacitor-transitions.

Safe areas con Tailwind

Per le safe area del dispositivo in Tailwind CSS, usa @capgo/tailwind-capacitor (pubblicato su 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 spargere env(safe-area-inset-*) manualmente. Il progetto è in fase di sviluppo attivo — se manca qualcosa per il tuo setup 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 web app Nuxt in app native iOS e Android usando Capacitor 8. Il tuo codebase Vue ora gira nativamente su dispositivi mobile con accesso alle API del dispositivo.

Cosa hai realizzato:

Configurazione di Nuxt per la generazione statica
Aggiunta di Capacitor 8 con i plugin essenziali
Build e deploy su simulatori iOS e Android
Abilitazione del live reload per lo sviluppo
Risolti i comuni problemi di layout su iOS (viewport, safe area, overflow)
Aggiunta un'interfaccia nativa con Capgo Native Navigation e Transitions

Prossimi passi:

Configurazione Capgo per aggiornamenti over-the-air senza dover ripubblicare l'app sugli 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 in 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.