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

Introduzione

Hai già un'applicazione web Nuxt? In questo guide, imparerai a trasformarla in applicazioni mobili native per iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorati 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 Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.

Ciò che imparerai:

• Configura la tua app Nuxt esistente per la generazione 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? Crea un'app mobile Nuxt da zero.

Benefits of Using Nuxt and Capacitor

• Code Reusability: Condividi i tuoi componenti Vue e logica tra app web e mobili.
• Performance: La generazione statica di Nuxt crea bundle ottimizzati perfetti per i dispositivi mobili.
• Funzionalità native: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
• Sviluppo semplificato: Utilizza i pattern Vue/Nuxt familiari senza dover imparare lo sviluppo nativo.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Node.js 18+ installato
• Un'applicazione esistente Nuxt 4 un'applicazione
• Xcode (per lo sviluppo di iOS, disponibile solo su macOS)
• Android Studio (per lo sviluppo di Android)

Configurazione dell'app Nuxt per dispositivi mobili

Il primo passo è configurare l'app Nuxt per la generazione statica. Capacitor richiede file HTML/JS/CSS statici per poterli bundle nella app nativa.

Assicurati che il tuo package.json abbia lo script di generazione:

{
  "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 stai utilizzando funzionalità server-side (API percorsi, middleware del server, ecc.), dovrai rifare quelle per utilizzare alternative client-side o API esterne.

Testa la generazione statica eseguendo:

bun run generate

Devi vedere un .output/public cartella con i tuoi file statici. Questo è ciò che Capacitor compatterà nel tuo app nativo.

Aggiungere Capacitor 8 al tuo Progetto

Per avvolgere il tuo app Nuxt in un contenitore mobile nativo, segui questi passaggi:

1. Installa Capacitor core e CLI:

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

2. Installa plugin Capacitor comuni che probabilmente avrai bisogno:

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

Questi plugin forniscono funzionalità essenziali:

• @capacitor/app: Gestisci gli eventi di ciclo di vita dell'applicazione (in primo piano/ in background, collegamenti profondi)
• @capacitor/keyboard: Controlla il comportamento del tastierino su dispositivi mobili
• @capacitor/splash-screen: Gestisci lo schermo di benvenuto nativo
• @capacitor/status-bar: Stila la barra dello stato del dispositivo
• @capacitor/preferences: Archiviazione di valori chiave (come localStorage ma nativa)

3. Inizializza Capacitor con i dettagli del tuo progetto:

bunx cap init my-app com.example.myapp --web-dir .output/public

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

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

5. Installa piattaforme native:

bun add @capacitor/ios @capacitor/android

6. Aggiungi le cartelle delle piattaforme native:

bunx cap add ios
bunx cap add android

Capacitor creerà ios e android cartelle al livello 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.

7. Esegui la costruzione e sincronizza il tuo progetto:

bun run mobile

Questo esegue lo script personalizzato che genera la costruzione statica di Nuxt e sincronizza i file 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, devi avere Xcode installato, e per app Android, devi avere Android Studio installato. Inoltre, se pianifichi di distribuire la tua app sul negozio di app, devi iscriverti al programma di sviluppatori Apple per iOS e al Google Play Console per Android.

1. Apre le progetti native:

Per iOS:

bun run mobile:ios

For Android:

bun run mobile:android

Ora direttamente con Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Esegui 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 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 programma sviluppatore di Apple). Una volta configurato, clicca sul pulsante "Gioca" per eseguire l'app sul tuo dispositivo connesso.

Congratulazioni! Hai distribuito con successo la tua app web 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 i cambiamenti istantaneamente sul tuo dispositivo mobile. Per abilitare questa funzionalità, segui questi passaggi:

1. Trova l'indirizzo IP locale:

• On macOS, esegui il seguente comando nel terminale:

  ipconfig getifaddr en0

• On Windows, esegui:

  ipconfig

  Cerca l'indirizzo IPv4 nell'output.

2. 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 l'indirizzo IP locale (ad esempio, 192.168.1.100).

3. Applica le modifiche al tuo progetto nativo:

bunx cap copy

La copy comando copia la cartella web e le modifiche di configurazione nel progetto nativo senza aggiornare l'intero progetto.

4. Inizia il tuo server di sviluppo Nuxt e ricostruisci in Xcode/Android Studio:

bun run dev

Now, every time you make changes to your Nuxt app, the mobile app will automatically reload to reflect those changes.

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

Using Capacitor Plugins

I plugin Capacitor consentono di accedere alle funzionalità del dispositivo nativo dal tuo'app Nuxt. Ecco un esempio: Plugin di condivisione come esempio:

1. Installa il plugin di condivisione:

bun add @capacitor/share

2. Crea o aggiorna una pagina per utilizzare il plugin di condivisione. In Nuxt 4, le pagine vanno 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>

3. Sincronizza le modifiche con il progetto nativo:

bun run mobile

O sincronizza senza ricostruire:

bunx cap sync

4. Ricostruisci e esegui l'app sul tuo dispositivo.

Now, when you click the “Condividi ora!” button, the native share dialog will appear.

Successivamente, puoi rendere l'app più nativa su iOS e Android con Capgo di navigazione e transizioni, e risolvere i problemi di layout comuni di iOS che causano overflow orizzontale o aree sicure tagliate.

Interfaccia utente con un aspetto nativo con Capgo di navigazione e transizioni native

Lavoro da anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Nuxt è un processo complicato e raramente vale la pena quando già hai Tailwind CSS.

Per un aspetto mobile nativo in un'app Nuxt + Capacitor, utilizza i plugin Capgo al posto delle kit UI web come Konsta UI:

• @capgo/capacitor-native-navigation — barra di navigazione nativa, Liquid Glass bar delle schede su iOS, e uno stile di barra delle schede sfocato su Android. Il tuo router Nuxt 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.

Installa entrambi:

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

Configura la navigazione nativa con il modo di inserimento CSS 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 sistema; Android utilizza un sfondo di 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 tuo contenitore di app:

<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 di routing in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima di navigare. Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede quelle superfici.

Vedi le guide complete: Utilizzando @capgo/capacitor-navigazione-nativa e Usando @capgo/capacitor-transizioni.

Zone sicure con Tailwind

Per le zone sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor Pubblicato su tailwind-capacitor on npm). Fornisce safe-areas utilità 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, mantenere questa importazione nel file CSS richiamato da nuxt.config.ts.

Utilizzare utilità come pt-safe, pb-safe, e px-safe al posto di disseminare env(safe-area-inset-*) con le proprie mani. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Nuxt, apri una PR su GitHub.

Il problema dei layout 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. Passa attraverso questi controlli in ordine.

Assicurati che il tag meta viewport sia applicato correttamente

In nuxt.config.ts, impostare il viewport tramite app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

Gestisci l'area di sicurezza iOS da un solo wrapper radice

Creare un unico contenitore dell'applicazione e applicare il padding dell'area di sicurezza lì — non in più componenti nidificati:

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

Avvolgi tutto il contenuto della pagina all'interno di .app-shellLa duplicazione del padding dell'area di sicurezza nei titoli, nei modali e nei wrapper di layout spesso fa sembrare il UI tagliato o troppo grande.

With @capgo/tailwind-capacitor, puoi esprimere la stessa spaziatura con utilità come pt-safe pb-safe px-safe su quella singola shell.

Imposta Capacitor iOS contentInset su never context: Pagina/Area: Pagina prodotti di aggiornamenti in tempo reale. Ruolo: Etichetta UI breve o elemento di navigazione. Chiave di messaggio `live_update_dynamic_label_to` (Etichetta dinamica di aggiornamento in tempo reale To).

primo capacitor.config.tsIn contentInsetMode: 'css', preferisci l'inserzione nativa disabilitata e lascia che CSS (o la navigazione nativa') gestisca l'area sicura:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

Mischia Capacitor’s automatico contenuto insetto con CSS env(safe-area-inset-*) la spaziatura di padding è una causa comune di doppia spaziatura.

Trova l'elemento che si sta sovrapponendo

Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screen, una larghezza in pixel fisse, 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 sovrapposizione orizzontale derivano da 100vw / w-screen, padding di area sicura duplicato, o un contenitore di larghezza fissa — non dal tag meta viewport stesso.

Conclusioni

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

Cosa hai ottenuto:

• Configurato Nuxt per generazione 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 UI con aspetto nativo con Capgo Native Navigation e Transizioni

Passaggi successivi:

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

Iniziare un nuovo progetto? Consulta Creare un'app mobile Nuxt da zero per una guida passo dopo passo.

Risorse

• Documentazione Nuxt
• Capacitor 8 Documentazione
• @ capgo/ capacitor-navigazione-nativa — Liquid Glass barra di navigazione e chrome nativo
• @ capgo/ capacitor-transizioni — transizioni di pagina con un sentimento nativo
• @ capgo/ tailwind-capacitor – Strumenti di utilizzo sicuro di Tailwind per l'area di sicurezza di Capacitor
• Capgo - Aggiornamenti in tempo reale per le Capacitor Applicazioni

Scopri come Capgo possa aiutarti a costruire applicazioni migliori in modo più veloce iscrivi il tuo account gratuito oggi.

Continua a lavorare da Converti la tua App Nuxt in iOS & Android con Capacitor 8

Se stai utilizzando Converti la tua App Nuxt in iOS & Android con Capacitor 8 per pianificare il lavoro dei plugin nativi, collega 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 Aggiunta o Aggiornamento di Plugin per i dettagli di implementazione in Aggiunta o Aggiornamento di Plugin Sostituti di Plugin Enterprise di Ionic per il workflow del prodotto in Sostituti di Plugin Enterprise di Ionic, e Capgo Build Nativo per il workflow del prodotto in Capgo Build Nativo