Converti la tua App Nuxt in iOS & Android con Capacitor 8

Introduzione

Hai un'applicazione web Nuxt esistente? In questa guida, imparerai a trasformarla in app mobili native iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorata e nuove funzionalità.

Capacitor avvolge la tua app web in un contenitore nativo, fornendoti l'accesso a API come la fotocamera, il filesystem e le notifiche push, mantenendo intatta la tua base di codice Vue esistente. A differenza di Flutter o React Native, non hai bisogno di ri-scrittura nulla — il tuo Nuxt code funziona così com'è.

Quello che imparerai:

• Configura la tua app Nuxt esistente per la generazione statica
• Aggiungi Capacitor 8 con plugin nativi essenziali
• Costruisci e testa sui simulatori di iOS e Android
• Abilita il reload live per un sviluppo più veloce
• Risolve i problemi di layout comuni di iOS (viewport, area sicura, sovrapposizione orizzontale)
• Aggiungi un'interfaccia utente che sembra nativa con Capgo Native Navigation e Transitions

Cercando di iniziare un nuovo progetto da zero? Consulta la nostra guida su Costruire un'app mobile Nuxt da zero.

I benefici dell'uso di Nuxt e Capacitor

• Code Reutilizzabilità: Condividi i tuoi componenti Vue e la logica tra app web e mobili.
• Performance: La generazione statica di Nuxt crea pacchetti ottimizzati perfetti per i dispositivi mobili.
• Funzionalità native: Accedi alle funzionalità del dispositivo come fotocamera, geolocalizzazione e filesystem attraverso i plugin Capacitor.
• Sviluppo semplificato: Utilizza modelli familiari Vue/Nuxt senza dover imparare lo sviluppo nativo.

Prerequisiti

: Prima di iniziare, assicurati di avere:

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

Configurazione della tua App Nuxt per dispositivi mobili

La prima cosa da fare è configurare la tua app Nuxt per la generazione statica. Capacitor richiede file HTML/JS/CSS statici per poterli bundle nella app nativa.

Assicurati che la tua package.json context:HTML text fragment from a longer Capgo UI string (parent key `solutions_cordova_to_capacitor_ai_step2_body`). Page/area: Capgo solutions marketing page. Role: Website copy sentence. Seen in: page solutions/cordova-to-capacitor-ai.astro. Message key `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body).

{
  "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"
  }
}

abbia lo script di generazione: Importante: se utilizzi funzionalità server-side (API percorsi, middleware server, ecc.), dovrai rifare quelle per utilizzare alternative client-side o API esterne.

Verifica 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 pacchettizzare la tua 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 i plugin Capacitor comuni che ti serviranno probabilmente:

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'app (in primo piano/ background, collegamenti profondi)
• @capacitor/keyboard: Controlla il comportamento del tastierino su mobile
• @capacitor/schermo di benvenuto: Gestisci lo schermo di benvenuto nativo
• @capacitor/barra dello stato: Stile la barra dello stato del dispositivo
• @capacitor/preferenze: 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 nome della tua app e com.example.myapp con l'ID della tua app (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 alle radici 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. Costruisci e sincronizza il tuo progetto:

bun run mobile

Questo esegue il tuo script personalizzato che genera la costruzione statica Nuxt e sincronizza i file con le piattaforme native.

Costruzione e distribuzione di App native

To costruire e distribuire la tua app mobile nativa, segui questi passaggi:

To sviluppare app iOS, devi avere Xcode installato, e per le app Android, devi 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.

1. Apre le progetti nativi:

Per iOS:

bun run mobile:ios

Per Android:

bun run mobile:android

O direttamente con Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Costruisci e esegui l'app:

• In Android Studio, attendi che il progetto sia pronto e clicca quindi sul pulsante “Esegui” per distribuire l'applicazione su un dispositivo o emulatore collegato.

• In Xcode, configura il tuo account di firma per distribuire l'applicazione su un dispositivo reale. Se non hai fatto ciò prima, Xcode ti guiderà attraverso il processo (nota che devi essere iscritto al programma di sviluppo Apple). Una volta configurato, clicca sul pulsante “Gioca” per eseguire l'applicazione sul tuo dispositivo collegato.

Congratulazioni! Hai con successo distribuito la tua app web Nuxt su un dispositivo mobile.

Ma aspetta, c'è anche un modo più veloce di fare ciò 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. Cerca il tuo indirizzo IP locale:

• Sul macOS, esegui il seguente comando nel terminale:

  ipconfig getifaddr en0

• Sul Windows, esegui:

  ipconfig

  Cerca l'indirizzo IPv4 nell'output.

2. Aggiorna il capacitor.config.ts a 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 es. 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. Avvia il tuo server di sviluppo Nuxt e ricostruisci in Xcode/Android Studio:

bun run dev

Ora, ogni volta che apporti modifiche al tuo'app Nuxt, l'app mobile si ricaricherà automaticamente per riflettere quelle modifiche.

Nota: Se installi nuovi plugin o apporti modifiche a file nativi, dovrai ricostruire il progetto nativo poiché la ricarica in tempo reale si applica solo alle modifiche web code.

Utilizzo dei Capacitor Plugin

Capacitor plugin ti consente di accedere alle funzionalità del dispositivo nativo dal tuo'app Nuxt. Esploriamo come utilizzare il plugin Condividi come esempio:

1. Installa il plugin Condividi:

bun add @capacitor/share

2. Creare o aggiornare una pagina per utilizzare il plugin Condividi. 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.

Ora, quando clicchi sul pulsante 'Condividi ora!', apparirà il dialogo di condivisione nativo.

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

Interfaccia utente nativa con Capgo Navigazione e transizioni native

Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarlo con Nuxt è un po' ingessato e raramente vale la pena quando già hai Tailwind CSS.

Per un aspetto nativo su un'app Nuxt + Capacitor utilizza i plugin Capgo al posto di kit UI web come Konsta UI:

• @capgo/capacitor-native-navigation — barra di navigazione nativa, Liquid Glass bar delle schede su iOS e una barra delle schede sfocata su Android. Il tuo router Nuxt mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
• @capgo/capacitor-transitions — transizioni di pagina stile Ionic e swipe indietro con l'edge su iOS nel layer WebView, senza adottare l'UI di Ionic.

Installate entrambi:

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

Configura la navigazione nativa con il CSS inset mode affinché il contenuto web rispetti le barre native:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendi una barra delle schede 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 contenitore dell'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>

Avvolgere le pagine di routing in cap-router-outlet, cap-page, e cap-content, e chiamare setDirection('forward') o setDirection('back') prima di navigare. Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa gestisce quelle superfici.

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

Aree sicure con Tailwind

Per le aree sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor (pubblicato come) tailwind-capacitor su npm). Offre safe-areas strumenti e altri plugin Capacitor-amici di Tailwind:

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 questa importazione nel file CSS riferito da nuxt.config.ts.

Utilizza strumenti come pt-safe, pb-safe, e px-safe al posto di aggiungerli env(safe-area-inset-*) manualmente. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione di Nuxt, apri una PR su GitHub.

Risolvere problemi di layout iOS (Viewport, Area sicura, e sovrapposizione orizzontale)

Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o semplice regolazione della tag viewport o la sua modifica non risolve il problema. Esegui questi controlli in ordine.

Assicurati che la tag meta viewport sia applicata 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',
        },
      ],
    },
  },
});

Tratta l'area di sicurezza di iOS da un solo wrapper radice.

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

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-shellUn doppio padding dell'area di sicurezza nei moduli, nelle intestazioni e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande.

Con @capgo/tailwind-capacitorpuoi esprimere lo stesso padding con utilità come pt-safe pb-safe px-safe su quel singolo contenitore.

Configura Capacitor iOS contentInset su never per

prima capacitor.config.tsIn contentInsetMode: 'css', preferisci l'ingombro nativo disabilitato e lascia che CSS (o la navigazione nativa)

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-*) Mescolare l'ingombro automatico di contenuto di __CAPGO_KEEP_0__ con CSS

è una causa comune di doppia interlinea.

Cerca l'elemento che sta veramente sovrapprendendo 100vwL'elemento solito colpevole è un elemento che utilizza w-screen, Tailwind, una larghezza fissa in pixel, o una larghezza molto 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-screenpadding di area sicura duplicato, o da un contenitore di larghezza fissata — non dal tag meta viewport stesso.

Conclusioni

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

Cosa hai ottenuto:

• Configurato Nuxt per la generazione statica
• Aggiunto Capacitor 8 con plugin essenziali
• Costruito e distribuito ai simulatori iOS e Android
• Abilitato il reload live per lo sviluppo
• Risolti problemi di layout iOS comuni (viewport, area sicura, overflow)
• Aggiunto un'interfaccia utente che sente di essere nativa con Capgo Navigazione e Transizioni native

Passaggi successivi:

• Configura Capgo per aggiornamenti senza app store resubmission
• Aggiungi più plugin nativi come Camera, Geolocalizzazione o Notifiche Push
• Configura icone e schermate di avvio per la produzione
• Prepara il tuo app per la sottoscrizione di App Store e Google Play

Iniziando un nuovo progetto? Controlla Crea un'app mobile Nuxt da zero per una guida passo dopo passo.

Risorse

• Dal Documentazione di Nuxt
• Capacitor 8 Documentazione
• @ capgo/capacitor-navigazione-nativa — Barra di navigazione Liquida Glass e chrome nativo
• @ capgo/capacitor-transizioni — Transizioni di pagina con un sentimento nativo
• @ capgo/tailwind-capacitor — Utilità di area sicura di Tailwind per Capacitor
• Capgo - Aggiornamenti in tempo reale per le App Capacitor

Scopri come Capgo possa aiutarti a costruire app migliori in modo più veloce, iscrivi un account gratuito oggi.

Continua con Converti il tuo App Nuxt in iOS & Android con Capacitor 8

Se stai utilizzando Converti il tuo App Nuxt 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 Capacitor Plugin da Capgo per i dettagli di implementazione in Capacitor Plugin da Capgo Aggiornamento o Aggiunta dei Plugin per i dettagli di implementazione in Aggiornamento o Aggiunta dei Plugin Alternative per Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternatives Plugin Ionic Enterprise Capgo Costruzione nativa per il flusso di lavoro del prodotto in Capgo Costruzione nativa.