Costruisci un'app mobile Nuxt da zero con Capacitor 8

Introduzione

Vuoi creare un'app mobile con Nuxt dall'alto in basso? Questa guida ti guida attraverso la creazione di un nuovo progetto Nuxt 4 configurato per la mobilità fin dal primo giorno, quindi pacchettizzato come app native iOS e Android utilizzando Capacitor 8.

Con la fine di questa guida, avrai un'app mobile funzionante che esegue su simulatori che puoi continuare a sviluppare e pubblicare infine sullo Store App e Google Play.

Tempo richiesto: ~30 minuti

Cosa costruirai:

Un nuovo progetto Nuxt 4 con la struttura di directory più recente
Configurazione di generazione statica per la mobilità
Capacitor 8 con plugin essenziali
Applicazioni iOS e Android native
Impostazione di sviluppo con reload in tempo reale

Hai già un'app Nuxt? Converti la tua app Nuxt in mobile invece.

Prerequisiti

Assicurati di avere installati:

Node.js 18+ (controlla con node --version)
Bun gestore di pacchetti (curl -fsSL https://bun.sh/install | bash)
Xcode (solo per macOS, per lo sviluppo di iOS)
Android Studio (per lo sviluppo di Android)

Passo 1: Crea un nuovo progetto Nuxt 4

Inizia creando un nuovo progetto Nuxt 4 fresco:

bunx nuxi@latest init my-mobile-app
cd my-mobile-app
bun install

Struttura di directory di Nuxt 4

Nuxt 4 utilizza una nuova struttura di directory con app code nella app/ directory:

my-mobile-app/
  app/
    assets/
    components/
    composables/
    layouts/
    middleware/
    pages/
    plugins/
    utils/
    app.vue
  public/
  server/
  nuxt.config.ts
  package.json

Questa struttura fornisce una separazione migliore tra app e server code.

Passo 2: Configura Nuxt per la generazione statica

Capacitor richiede file HTML/JS/CSS statici. Configura Nuxt per la generazione statica in nuxt.config.ts:

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  // Enable static generation
  ssr: true,
  nitro: {
    preset: 'static',
  },
});

Passo 3: Aggiungi script mobili

Aggiorna il tuo package.json con script di sviluppo mobile:

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

Testa la generazione statica:

bun run generate

Dovresti vedere una .output/public cartella con i tuoi file statici.

Passo 4: Installa Capacitor 8

Installa i pacchetti di base di Capacitor:

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

Installa plugin essenziali che la maggior parte delle app mobili richiede:

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

Cosa fanno questi plugin:

@capacitor/app — Eventi di ciclo di vita dell'app (in primo piano/ in background, collegamenti profondi)
@capacitor/keyboard — Controllo del comportamento della tastiera
@capacitor/schermo di benvenuto — Controllo dello schermo di benvenuto nativo
@capacitor/barra dello stato — Personalizza la barra dello stato del dispositivo
@capacitor/preferenze — Archiviazione dei valori chiave (come localStorage ma nativa)

Passo 5: Inizia Capacitor

Inizia Capacitor con i dettagli del tuo progetto:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir .output/public

Sostituisci:

"My Mobile App" con il nome della tua app
com.example.mymobileapp con l'ID della tua app (notazione di dominio inverso)

Questo crea capacitor.config.tsAggiornalo con la configurazione del plugin:

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

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile 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;

Passo 6: Aggiungi piattaforme native

Installa i pacchetti delle piattaforme:

bun add @capacitor/ios @capacitor/android

Genera i progetti nativi:

bunx cap add ios
bunx cap add android

Questo crea ios e android directory che contengono i progetti nativi.

Passo 7: Costruisci e Esegui

Costruisci il tuo progetto e sincronizza con le piattaforme native:

bun run mobile

Apri in iOS Simulator:

bun run mobile:ios

O Android Emulator:

bun run mobile:android

In Xcode (iOS):

Seleziona un simulatore dal menu a discesa dei dispositivi
Clicca sul pulsante di riproduzione o premi Cmd + R

In Android Studio:

Aspetta che Gradle finisca di sincronizzare
Seleziona un emulatore dal menu a discesa dei dispositivi
Clicca sul pulsante di esecuzione o premi Shift + F10

Passo 8: Configura Live Reload

Per un sviluppo più veloce, abilita live reload per visualizzare i cambiamenti istantaneamente sul tuo dispositivo.

Trova l'indirizzo IP locale:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Crea una configurazione di sviluppo Capacitor. Aggiorna capacitor.config.ts:

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

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: '.output/public',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

Avvia il server di sviluppo e copia la configurazione nella versione nativa:

bun run dev &
NODE_ENV=development bunx cap copy

Riavvia in Xcode/Android Studio

Ora le modifiche ai tuoi Nuxt code si ricaricheranno automaticamente sul dispositivo.

Passo 9: Crea la Prima Schermata Mobile

Crea una schermata di benvenuto adatta ai dispositivi mobili. Aggiorna app/app.vue:

<template>
  <NuxtPage />
</template>

Crea app/pages/index.vue:

<template>
  <main
    class="min-h-screen bg-linear-to-b from-green-500 to-green-700 flex flex-col items-center justify-center p-6 text-white"
  >
    <h1 class="text-4xl font-bold mb-4">My Mobile App</h1>
    <p class="text-xl mb-8 text-center opacity-90">
      Built with Nuxt 4 + Capacitor 8
    </p>

    <div v-if="appInfo" class="bg-white/20 rounded-lg p-4 backdrop-blur-sm mb-8">
      <p class="text-sm">
        {{ appInfo.name }} v{{ appInfo.version }}
      </p>
    </div>

    <div class="space-y-4 w-full max-w-sm">
      <button
        class="w-full py-4 px-6 bg-white text-green-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform"
        @click="handleGetStarted"
      >
        Get Started
      </button>
      <button
        class="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform"
        @click="handleShare"
      >
        Share App
      </button>
    </div>
  </main>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';

const appInfo = ref<{ name: string; version: string } | null>(null);

let backButtonListener: { remove: () => void } | null = null;

onMounted(async () => {
  // Get app info
  try {
    appInfo.value = await App.getInfo();
  } catch (e) {
    // Web fallback
    appInfo.value = { name: 'My Mobile App', version: '1.0.0' };
  }

  // Handle Android back button
  backButtonListener = await App.addListener('backButton', ({ canGoBack }) => {
    if (!canGoBack) {
      App.exitApp();
    } else {
      window.history.back();
    }
  });
});

onUnmounted(() => {
  backButtonListener?.remove();
});

function handleGetStarted() {
  // Navigate to onboarding or main app
  console.log('Get started clicked');
}

async function handleShare() {
  // We'll implement this with the Share plugin later
  console.log('Share clicked');
}
</script>

Passo 10: Aggiungi Tailwind CSS

Perché il styling funzioni, aggiungi Tailwind CSS al tuo progetto:

bun add tailwindcss @tailwindcss/vite

Aggiorna nuxt.config.ts:

import tailwindcss from '@tailwindcss/vite';

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  ssr: true,
  nitro: {
    preset: 'static',
  },

  css: ['~/assets/css/main.css'],

  vite: {
    plugins: [tailwindcss()],
  },
});

Crea app/assets/css/main.css:

@import 'tailwindcss';

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input,
textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

Crea la funzionalità del pulsante di condivisione:

bun add @capacitor/share

Aggiorna app/pages/index.vue per utilizzare il plugin di condivisione:

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@capacitor/app';
import { Share } from '@capacitor/share';

// ... existing code ...

async function handleShare() {
  try {
    await Share.share({
      title: 'Check out this app!',
      text: 'Built with Nuxt 4 and Capacitor 8',
      url: 'https://capacitorjs.com',
      dialogTitle: 'Share with friends',
    });
  } catch (e) {
    console.log('Share cancelled or failed:', e);
  }
}
</script>

Sync e ricostruisci:

bun run mobile

Struttura del progetto

Il tuo progetto dovrebbe ora avere questo aspetto:

my-mobile-app/
├── android/                  # Android native project
├── ios/                      # iOS native project
├── .output/
│   └── public/              # Static build output
├── app/
│   ├── assets/
│   │   └── css/
│   │       └── main.css
│   ├── pages/
│   │   └── index.vue
│   └── app.vue
├── capacitor.config.ts       # Capacitor configuration
├── nuxt.config.ts            # Nuxt configuration
├── package.json
└── ...

Passaggi successivi

Prossimi passaggi

Configurazione essenziale

Iconografie dell'app Sostituisci icone di default in ios/App/App/Assets.xcassets E android/app/src/main/res
Schermo di benvenuto personalizzato: Personalizza in progetti nativi o utilizza @capacitor/splash-screen config
Deep Links: Configura i schemi di URL per la tua app

Aggiungi più funzionalità

Camera: bun add @capacitor/camera
Geolocalizzazione: bun add @capacitor/geolocation
Push Notifications: bun add @capacitor/push-notifications o @capgo/capacitor-firebase-messaging @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-firebase-messaging
per Firebase Cloud Messaging su iOS e Android bun add @capacitor/filesystem

File System: (Sistema di file: )

Usa Capgo plugin al posto di Konsta UI per un aspetto nativo del mobile:

@capgo/capacitor-navigazione-nativa — barra di navigazione Liquida Glass e navbar nativa
@capgo/capacitor-transizioni — transizioni di pagina con un aspetto nativo

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

Per aree sicure di Tailwind, aggiungi @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Vedi Usare @capgo/capacitor-navigazione-nativa, Usare @capgo/capacitor-transizioni, e il repo tailwind-capacitor per la configurazione specifica di Nuxt.

Risolvere i problemi di layout di 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 solo la riga del tag viewport non risolve di solito il problema. Esegui questi controlli in ordine.

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

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

Crea un unico contenitore dell'app e applica la spaziatura di sicurezza dell'area lì — non nei 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-shellLa duplicazione della spaziatura di sicurezza dell'area nei capisaldi, nelle finestre modal e nei wrapper di layout spesso fa sembrare il UI tagliato o troppo grande.

Con @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` a `never` primo

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

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

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

Trova l'elemento che sta veramente sovrascrivendo

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

Aggiornamenti Over-the-Air

Configura Capgo per inviare aggiornamenti senza la riconferma dell'app store:

bunx @capgo/cli init

Risolvere i problemi

Costruzione fallita con "Cannot find module" Esegui bun install e riprova.

iOS: "No signing identity found" Apre Xcode, vai a Signing & Capabilità, e seleziona il tuo team di sviluppo.

Android: "SDK location not found" Crea android/local.properties con sdk.dir=/path/to/android/sdk

Le modifiche non si visualizzano sul dispositivo Assicurati di aver eseguito bun run mobile dopo aver apportato modifiche. Per il live reload, verifica l'indirizzo IP è corretto e il server di sviluppo è in esecuzione.

.output/public è vuoto o mancante Assicurati di aver configurato nitro: { preset: 'static' } in nuxt.config.ts e esegui bun run generate.

Risorse

Pronto a distribuire il tuo app? Scopri come Capgo può aiutarti a consegnare aggiornamenti più velocemente — iscrivi per un account gratuito oggi.

Continua da Costruisci un'app mobile Nuxt da zero con Capacitor 8

Se stai utilizzando Costruisci un'app mobile Nuxt da zero con Capacitor 8 per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni for the product workflow in Capgo Integrations, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Integrazione azioni per i dettagli di implementazione in GitHub Integrazione azioni.

Build a Nuxt Mobile App from Scratch with Capacitor 8