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

Introduzione

Hai già un'applicazione web Nuxt? In questo tutorial, imparerai a trasformarla in applicazioni mobili native per iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorata e nuove funzionalità.

Capacitor avvolge la tua applicazione web in un contenitore nativo, fornendoti accesso a API di dispositivo come la fotocamera, il filesystem e le notifiche push, mantenendo il tuo codice esistente Vue. A differenza di Flutter o React Native, non devi riscrivere nulla — la tua applicazione Nuxt code funziona com'è.

Cosa imparerai:

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

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

I benefici dell'utilizzo di Nuxt e Capacitor

• La reutilizzabilità di Code: Condividi i tuoi componenti Vue e logica tra app web e mobili.
• Performance: La generazione statica di Nuxt crea bundle ottimizzati perfetti per il mobile.
• Capacità native: Accesso alle funzionalità del dispositivo come camera, geolocalizzazione e filesystem attraverso Capacitor plugin.
• Sviluppo Semplificato: Utilizza pattern Vue/Nuxt familiari senza dover imparare lo sviluppo nativo.

Prerequisites

: Prima di iniziare, assicurati di avere:

• Node.js 18+ installato
• Un esistente Nuxt 4 applicazione
• Xcode (per iOS sviluppo, 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 nell'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 utilizzando alternative client-side o API esterne.

Testa la generazione statica eseguendo:

bun run generate

Vorresti vedere una .output/public cartella con i tuoi file statici. Questo è ciò che Capacitor compilerà nel tuo app nativa.

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 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 eventi di ciclo di vita dell'app (in primo piano/ background, collegamenti profondi)
• @capacitor/keyboard: Controlla il comportamento del tastierino su mobile
• @capacitor/splash-screen: Gestisci lo schermo di benvenuto nativo
• @capacitor/status-bar: Stilizza la barra dello stato del dispositivo
• @capacitor/preferences: Archiviazione chiave-valore (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 del tuo app e com.example.myapp : con l'ID dell'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. : Installare 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 le cartelle delle piattaforme native alla radice del tuo progetto.

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.

Costruire e Distribuire Applicazioni Native

Per costruire e distribuire la tua applicazione mobile nativa, segui questi passaggi:

To sviluppare app iOS, hai bisogno di avere Xcode installato, e per le app Android, hai bisogno di avere Android Studio installato. Inoltre, se pianifichi di distribuire la tua app sul negozio di app, hai bisogno di iscriverti al Apple Developer Program 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 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'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 connesso.

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

Ma aspetta, c'è anche un modo più veloce per farlo durante lo sviluppo…

Capacitor Ricostruzione in tempo reale

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

Ripristina 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 La comanda 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é il ricaricamento in tempo reale si applica solo alle modifiche web code.

Utilizzo dei Capacitor Plugin

Capacitor plugin consentono di accedere alle funzionalità del dispositivo nativo dal tuo'app Nuxt. Esploriamo come utilizzare i Condividi plugin ad 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 To costruire applicazioni cross-platform, ma integrarla con Nuxt è un po' artigianale e raramente vale la pena quando già ne hai una. 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-navigazione nativa --- barra di navigazione nativa, Liquid Glass bar delle schede su iOS e stile di barra delle schede sfocata su Android. Il tuo router Nuxt mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
• @capgo/capacitor-transizioni --- transizioni di pagina stile Ionic e swipe indietro su iOS nella layer WebView, senza adottare l'UI di Ionic.

Installa entrambi:

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

Configura la navigazione nativa con modalità CSS inset 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',
  },
});

Visualizza un pannello di navigazione Liquido Glass (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 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>

Avvolgi le pagine di destinazione in cap-router-outlet, cap-pagee, e cap-contente, chiama setDirection('forward') o setDirection('back') Prima di navigare. Non ripetere i titoli o i piedi di pagina web quando la navigazione nativa gestisce queste aree.

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

Zone sicure con Tailwind

Per le aree sicure del dispositivo in Tailwind CSS, utilizza @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Offre safe-areas utilità e altri plugin di 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 questa importazione nel file CSS richiamato da nuxt.config.ts.

Utilizza utilità come pt-safe, pb-safe, e px-safe al posto di aggiungerle 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 di sicurezza, e sovrapposizione orizzontale)

Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o regolare 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 sicura di iOS da un wrapper root solo

Creare un unico contenitore dell'applicazione e applicare il padding dell'area sicura 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 .app-shellIl sovrapposizionamento di padding di area sicura in intestazioni, modali e wrapper di layout può rendere l'interfaccia utente appiattita o troppo grande.

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

Imposta Capacitor iOS contentInset a never primo

In capacitor.config.ts, preferisci l'ingombro nativo disabilitato e lascia che CSS (o la navigazione nativa) contentInsetMode: 'css'possa gestire l'area sicura:

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

Mixing Capacitor’s automatic content inset con CSS env(safe-area-inset-*) Trova l'elemento che sta effondando realmente

Il solito colpevole è un elemento che utilizza

Il colpevole più comune è un elemento che utilizza 100vw, Tailwind w-screenIn Safari Web Inspector, esegui: 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 del viewport stesso.

Conclusioni

Hai convertito con successo 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 di dispositivo.

Cosa hai ottenuto:

• Configurato Nuxt per la generazione statica
• Aggiunto Capacitor 8 con plugin essenziali
• Costruito e distribuito su simulatori iOS e Android
• Abilitato il reload live per lo sviluppo
• Risolto comuni problemi di layout iOS (viewport, area sicura, sovrapposizione)
• Aggiunto UI con sentore nativo con Capgo Navigazione e Transizioni native

Next steps:

• Configura Capgo per aggiornamenti via rete senza riconferma dell'applicazione negli store
• Aggiungi più plugin nativi come Camera, Geolocalizzazione o Notifiche Push
• Configura icone e schermate di avvio per la produzione
• Prepara l'app per la sottoscrizione a App Store e Google Play

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

Risorse

• Nuxt Documentation
• Capacitor 8 Documentazione
• @capgo/capacitor-navigazione-nativa --- Pannello di navigazione Liquido 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 creare app migliori in modo più veloce iscrivi il tuo account gratuito today.

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 Aggiungere o Aggiornare i Plugin per i dettagli di implementazione in Aggiungere o Aggiornare i Plugin Alternative per Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternative Plugin Enterprise Ionic Capgo Native Builds per il workflow del prodotto in Capgo Costruzioni native.