Creare app mobile con Vue e Capacitor

In questo tutorial, ti guideremo nel processo di conversione di un'app web Vue in un'app mobile nativa usando Capacitor. Puoi anche aggiungere Capgo Native Navigation e Transitions per un feeling nativo, e usare tailwind-capacitor per le safe areas.

Informazioni su Capacitor

Capacitor è uno strumento rivoluzionario che permette di integrarsi facilmente in qualsiasi progetto web per convertire la tua applicazione in un'app mobile nativa. Genera automaticamente i progetti Xcode e Android Studio e fornisce l'accesso alle feature native del dispositivo, come la fotocamera, tramite un bridge JavaScript.

Preparazione della tua App Vue

Per prima cosa, crea una nuova app Vue eseguendo questo comando:

vue create my-app
cd my-app
npm install

Per preparare la tua app Vue al deployment mobile nativo, dovrai esportare il progetto. Aggiungi uno script nel tuo package.json per buildare e copiare il progetto Vue:

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

Dopo aver eseguito il comando build dovresti vedere una nuova dist cartella nella root del progetto. Questa cartella verrà utilizzata in seguito da Capacitor.

Aggiungere Capacitor alla tua app Vue

Per convertire la tua web app Vue in un container mobile nativo, segui questi passaggi:

Installa Capacitor CLI come dev dependency e configuralo nel progetto. Accetta i valori di default per name e bundle ID durante il setup.
Installa il pacchetto core e i pacchetti necessari per le piattaforme iOS e Android.
Aggiungi le piattaforme e Capacitor creerà le cartelle per ogni piattaforma nella root del progetto:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Vue project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

Ora dovresti vedere le nuove iOS e android cartelle nel tuo progetto Vue.

Aggiorna il file capacitor.config.json per puntare il webDir al risultato del tuo comando di build:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

Ora puoi buildare il tuo progetto Vue e sincronizzarlo con Capacitor:

npm run build
npx cap sync

Build e Deploy di Native Apps

Per sviluppare app iOS, devi avere Xcode installato, mentre per Android serve Android Studio. Inoltre, devi iscriverti all'Apple Developer Program per iOS e alla Google Play Console per Android per distribuire la tua app sugli store.

Usa Capacitor CLI per aprire entrambi i progetti nativi:

npx cap open ios
npx cap open android

Distribuisci la tua app su un dispositivo connesso usando Android Studio o Xcode.

Capacitor Live Reload

Abilita il live reload sul tuo dispositivo mobile facendo caricare all'app Capacitor i contenuti da un URL specifico della tua rete.

Trova il tuo indirizzo IP locale e aggiorna il capacitor.config.ts file con l'IP e la porta corretti:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:8080',
    cleartext: true
  }
};

export default config;

Applica queste modifiche copiandole nel tuo progetto nativo:

npx cap copy

Ora la tua app si ricaricherà automaticamente mostrando le modifiche ogni volta che aggiorni la tua app Vue.

Utilizzo dei plugin Capacitor

Installa un plugin Capacitor, come il plugin Share, e usalo nella tua app Vue:

npm i @capacitor/share

Importa il pacchetto e chiama il share() funzione nella tua app:

<template>
  <div>
    <h1>Welcome to Vue and Capacitor!</h1>
    <button @click="share">Share now!</button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function share() {
  await Share.share({
    title: 'Open Youtube',
    text: 'Check new video on youtube',
    url: 'https://www.youtube.com',
    dialogTitle: 'Share with friends'
  });
}
</script>

Dopo aver installato i nuovi plugin, esegui il comando sync e fai il redeploy dell'app sul tuo dispositivo:

npx cap sync

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 applicazioni cross-platform, ma integrarlo con Vue è complicato e raramente ne vale la pena se hai già Tailwind CSS.

Per un feeling mobile nativo in un'app Vue + 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 tuo Vue router 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 se la navigazione nativa gestisce quelle aree.

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

Safe area con Tailwind

Per le safe area del dispositivo in Tailwind CSS, usa @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Fornisce safe-areas utility e altri plugin Tailwind compatibili con Capacitor:

bun add -D tailwind-capacitor

In src/assets/main.css:

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

Usa utility come pt-safe, pb-safe, e px-safe invece di spargere env(safe-area-inset-*) manualmente. Il progetto è in attivo sviluppo — se manca qualcosa per il tuo setup Vue, 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

Aggiungi il meta tag viewport in index.html dentro <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 il padding della safe area lì — non in vari componenti annidati:

html,
body,
#app {
  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-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: 'dist',
  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 l'elemento che causa l'overflow

Il colpevole di solito è un elemento che usa 100vw, Tailwind w-screen, con 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

Capacitor è un'ottima opzione per creare applicazioni native partendo da un progetto web esistente. Con l'aggiunta di Capgo, è ancora più semplice aggiungere i Live Update alla tua app, garantendo agli utenti l'accesso immediato alle ultime funzionalità e bug fix.

Scopri come Capgo può aiutarti a creare app migliori più velocemente, registrati per un account gratuito oggi.

Continua il percorso: creare app mobile con Vue e Capacitor

Se stai usando Creare app mobile con Vue e Capacitor per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa in Utilizzo di @capgo/capacitor-video-player, @capgo/capacitor-video-player per i dettagli di implementazione in @capgo/capacitor-video-player, e Usando @capgo/capacitor-native-navigation per la funzionalità nativa in Usando @capgo/capacitor-native-navigation.