Convert Your Nuxt App to iOS & Android with Capacitor 8

Introduzione

Hai già un'applicazione web Nuxt esistente? In questo tutorial, imparerai a trasformarla in app mobili native per 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 di dispositivo come camera, filesystem e notifiche push, mentre mantiene il tuo codice esistente Vue. A differenza di Flutter o React Native, non hai bisogno di ri-scrittura nulla — la tua app Nuxt code funziona com'è.

Ciò che 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
• Risolvere problemi di layout iOS comuni (viewport, area sicura, overflow orizzontale)
• Aggiungere un'interfaccia utente che sente come nativa con Capgo Navigazione e Transizioni native

Se stai cercando di iniziare un nuovo progetto da zero? Costruire un'app mobile Nuxt da zero.

I benefici dell'utilizzo di Nuxt e Capacitor

• Code Reutilizzabilità: Condividi i tuoi componenti Vue e la logica tra app web e mobili.
• PerformanceRisorse: Pagina homepage sezione problema/soluzione. Ruolo: Intestazione di sezione o pagina. Visualizzato in: pagina premium-support.astro. Chiave messaggio `ps_help_performance_title` (Ps Aiuto Performance Titolo).
• : La generazione statica di Nuxt crea pacchetti ottimizzati perfetti per il mobile.: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
• : Accedi alle funzionalità del dispositivo come camera, geolocalizzazione e filesystem attraverso __CAPGO_KEEP_0__ plugin.: Utilizza modelli familiari Vue/Nuxt 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 (solo per lo sviluppo di iOS su macOS)
• Android Studio (solo per lo sviluppo di Android)

Configurare la tua App Nuxt per il Mobile

Il primo passo è configurare la tua 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 context

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

HTML testo frammento da una stringa Capgo UI più lunga (chiave padre `solutions_cordova_to_capacitor_ai_step2_body`). Pagina/area: Pagina di marketing delle soluzioni Capgo. Ruolo: Copia del sito web. Visualizzato in: pagina solutions/cordova-to-capacitor-ai.astro. Chiave messaggio `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body). If you’re using server-side features (API routes, server middleware, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Importante:

bun run generate

Se stai utilizzando funzionalità server-side (__CAPGO_KEEP_0__ percorsi, middleware server, ecc.), dovrai rifare quelle utilizzando alternative client-side o API esterne. .output/public folder with your static files. This is what Capacitor will bundle into your native app.

Adding Capacitor 8 to Your Project

cartella con i tuoi file statici. Questo è ciò che __CAPGO_KEEP_0__ bundlerà nella tua App nativa.

1. Install Capacitor core and CLI:

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

2. Installa i plugin comuni Capacitor 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, link 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. Inizia 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 del tuo 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 le 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 root del tuo progetto contenenti i progetti nativi.

Per costruire il progetto Android, hai bisogno Studio di Android. Per iOS, hai bisogno di un Mac con Xcode.

7. Costruisci e sincronizza il tuo progetto:

bun run mobile

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 app mobile nativa, segui questi passaggi:

Per sviluppare app iOS, devi avere Xcode installato, e per app Android, devi avere Studio di Android 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. Apri i 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'app su un dispositivo reale. Se non hai fatto ciò 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 avuto successo nel distribuire 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:

• Su macOS, esegui il seguente comando nel terminale:

  ipconfig getifaddr en0

• Su Windows, esegui:

  ipconfig

  Cerca l'indirizzo IPv4 nell'output.

2. Aggiorna il tuo 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 esempio, 192.168.1.100).

3. Applica i cambiamenti al tuo progetto nativo:

bunx cap copy

Il copy esegue una copia del folder 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

Ora, ogni volta che apporti modifiche al tuo'applicazione 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

Il Capacitor plugin consente di accedere alle funzionalità del dispositivo nativo dalla tua applicazione Nuxt. Esploriamo come utilizzare il 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

Ora 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 Capgo di navigazione e transizioni, e risolvi i problemi di layout comuni di iOS che causano overflow orizzontale o aree sicure tagliate.

Interfaccia utente con sentore nativo con Capgo di navigazione e transizioni native

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

Per un sentore mobile nativo in 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 barra dei tab su iOS, e uno stile di barra dei tab sfocato su Android. Il tuo router Nuxt mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
• @capgo/capacitor-transizioni — Transizioni di pagina simili a Ionic e swipe-back di iOS nell' layer WebView, senza adottare l'interfaccia utente di Ionic.

Installate sia:

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

Configurare la navigazione nativa con il modello di 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',
  },
});

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

Aggiungere 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 destinazione 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 possiede quelle superfici.

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

Aree sicure con Tailwind

Per le aree sicure del dispositivo in Tailwind CSS, utilizza @capgo/tailwind-capacitor (pubblicato su tailwind-capacitor npm safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

utilità e altri plugin di Tailwind compatibili con app/assets/css/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

__CAPGO_KEEP_0__: nuxt.config.ts.

Insieme a questo importa nel file CSS riferito da pt-safe, pb-safee, e px-safe al posto di aggiungere env(safe-area-inset-*) mano a mano. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Nuxt, open a PR on GitHub.

Risolvere Problemi di Layout iOS (Viewport, Area di Sicurezza, e Flusso 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. Esegui questi controlli in ordine.

Assicurati che il tag meta viewport sia applicato correttamente

In nuxt.config.tsimpostare il viewport attraverso 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 di iOS da un wrapper radice solo

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

Avvolgere tutto il contenuto della pagina all'interno .app-shell La duplicazione dello spazio di sicurezza dell'area sicura nei titoli, nelle finestre modal e nei contenitori di layout rende spesso l'interfaccia utente tagliata o troppo grande.

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

Imposta Capacitor iOS contentInset su never context: Pagina/area: Pagina di aggiornamenti in tempo reale. Ruolo: Etichetta di interfaccia utente breve o elemento di navigazione. Chiave di messaggio `live_update_dynamic_label_to` (Etichetta di aggiornamento dinamico per).

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',
  },
};

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

Trova l'elemento che sta effondando realmente

Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screen, un'ampiezza di pixel fissata, 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, sovrapposizione di padding sicura duplicata, o un contenitore di ampiezza fissata — non dal tag meta viewport stesso.

Conclusioni

You’ve successfully converted your existing Nuxt web application into native iOS and Android apps using Capacitor 8. Your Vue codebase now runs natively on mobile devices with access to device APIs.

Quello che avete realizzato:

• Configurato Nuxt per la generazione statica
• Added Capacitor 8 with essential plugins
• Costruito e distribuito su simulatori iOS e Android
• Abilitato il reload live per lo sviluppo
• Corretto problemi di layout iOS comuni (viewport, area sicura, overflow)
• Added native-feeling UI with Capgo Native Navigation and Transitions

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 l'app per la sottoscrizione a App Store e Google Play

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

Risorse

• Documentazione Nuxt
• Capacitor 8 Documentation
• @capgo/capacitor-native-navigation — Liquid Glass barra di navigazione e chrome nativo
• @capgo/capacitor-transitions — transizioni di pagina con un sentore di natività
• @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 oggi.

Continua 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, connettilo con Capgo Plugin Directory per il workflow del prodotto nella Capgo Directory dei Plugin Capacitor Plugin da Capgo per i dettagli di implementazione in Capacitor Plugin da Capgo Aggiunta o Aggiornamento dei Plugin per i dettagli di implementazione in Aggiunta o Aggiornamento dei Plugin Alternative per Plugin Enterprise di Ionic per il workflow del prodotto in Alternative per Plugin Enterprise di Ionic, e Capgo Costruzione Nativa per il workflow del prodotto in Capgo Costruzione Nativa