Crea 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 lo imballa come app native iOS e Android Capacitor 8.

Al termine di questo tutorial, avrai un'app mobile funzionante che esegue sui 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
• App native iOS e Android
• Setup di sviluppo con reload live

Già hai un'app Nuxt? Ecco cosa fare Converti la tua app Nuxt in mobile altrimenti.

Requisiti

Assicurati di avere installati:

• Node.js 18+ (controlla con node --version)
• Bun gestore dei 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:

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

Verifica la generazione statica:

bun run generate

Devi vedere una .output/public directory con i tuoi file statici.

Passo 4: Installa Capacitor 8

Installare i pacchetti core di Capacitor:

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

Installare i 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/ background, collegamenti profondi)
• @capacitor/keyboard – Controllo del comportamento della tastiera
• @capacitor/splash-screen — Controllo schermo di benvenuto nativo
• @capacitor/barra dello stato — Stile la barra dello stato del dispositivo
• @capacitor/preferenze — Archiviazione chiave-valore (come localStorage ma nativa)

Passo 5: Inizializza Capacitor

Inizializza 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 dell'app (notazione di dominio inverso)

Ciò crea capacitor.config.ts. Aggiornalo 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 contenenti 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):

1. Scegli un simulatore dal menu a discesa dispositivi
2. Clicca sul pulsante di riproduzione o premi Cmd + R

In Android Studio:

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

Passo 8: Configura il Live Reload

Per un sviluppo più veloce, abilita il live reload in modo che le modifiche apparano istantaneamente sul tuo dispositivo.

1. Trova l'indirizzo IP locale:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

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

3. Avvia il server di sviluppo e copia la configurazione nativa:

bun run dev &
NODE_ENV=development bunx cap copy

4. Riavvia in Xcode/Android Studio

Ora le modifiche al tuo Nuxt code si caricheranno automaticamente sul dispositivo.

Passo 9: Crea la Prima Scheda Mobili

Crea una home screen adatta per i 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;
}

Passo 11: Aggiungi il Plugin di Condivisione

Implementa la funzionalità del pulsante di condivisione:

bun add @capacitor/share

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

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

Sincronizza 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

Ora hai un'app mobile Nuxt funzionante. Ecco cosa fare successivamente:

Configurazione Fondamentale

• Icone dell'App: Sostituisci le icone predefinite in ios/App/App/Assets.xcassets e android/app/src/main/res
• Schermo di Avvio: Personalizza nei progetti nativi o utilizza @capacitor/splash-screen config
• Collegamenti Profondi: Configura i schemi di URL per la tua app

Aggiungi più funzionalità

• Camera: bun add @capacitor/camera
• Geolocalizzazione: bun add @capacitor/geolocation
• Notifiche Push: bun add @capacitor/push-notifications o @capgo/capacitor-firebase-messaging per Firebase Cloud Messaging su iOS e Android
• Sistema di file: bun add @capacitor/filesystem

Interfaccia nativa e transizioni

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

• @capgo/capacitor-native-navigation — Barra di navigazione Liquida Glass e navbar nativa
• @capgo/capacitor-transizioni — Transizioni di pagina con un sentimento 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 Utilizza @capgo/capacitor-navigazione nativa, Utilizza @capgo/capacitor-transizionie il repo tailwind-capacitor per la configurazione specifica di Nuxt.

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

If il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più o modificare la riga di taglio visore da solo non risolve di solito il problema. Lavora attraverso questi controlli in ordine. overflow-x: hidden Assicurati che la meta tag di taglio visore sia applicata correttamente

In

, impostare il taglio visore attraverso nuxt.config.tsGestisci l'area di sicurezza di iOS da un wrapper root solo app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

Crea un unico contenitore dell'app e applica il padding di area di sicurezza lì — non in componenti nidificati multipli:

Avvolgi tutto il contenuto della pagina all'interno

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

. Il padding di area di sicurezza duplicato nei titoli, nei modali e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande. .app-shellCon

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorIf il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più o modificare la riga di taglio visore da solo non risolve di solito il problema. Lavora attraverso questi controlli in ordine. pt-safe pb-safe px-safe in quel singolo shell.

Imposta Capacitor iOS contentInset su never primo

In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che 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-*) padding è una causa comune di doppia spaziatura.

Trova l'elemento che sta veramente sovrascrivendo

Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screenIn Safari Web Inspector, esegui: min-width.

Con Tailwind, sostituisci

[...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 w-screen quando possibile. Molti problemi di overflow orizzontale derivano da w-full , padding di area sicura duplicato, o un contenitore di larghezza fissata — non dal tag meta viewport stesso. 100vw / w-screenAggiornamenti Over-the-Air

Configura

__CAPGO_KEEP_0__ Capgo Risoluzione dei problemi

bunx @capgo/cli init

La compilazione fallisce con “Cannot find module”

Setup for Over-the-Air Updates Esegui e riprova. bun install Esegui e riprova.

iOS: “Identità di firma non trovata” Apri Xcode, vai a Signing & Capabilities e seleziona il tuo team di sviluppo.

Android: “SDK location not trovata” Crea android/local.properties con sdk.dir=/path/to/android/sdk

Il dispositivo non mostra le modifiche Sicuro di aver eseguito bun run mobile dopo aver fatto le modifiche. Per il live reload, verifica l'indirizzo IP è corretto e il server di sviluppo è in esecuzione.

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

Risorse

• Capacitor 8 Documentazione
• Documentazione Nuxt 4
• Capgo - Aggiornamenti in tempo reale
• @capgo/capacitor-navigazione nativa
• @capgo/capacitor-transizioni
• @capgo/tailwind-capacitor

Pronto a distribuire il tuo app? Scopri come Capgo può aiutarti a consegnare aggiornamenti più velocemente — iscrivi il tuo 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 per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e Azioni di integrazione di GitHub per i dettagli di implementazione in Azioni di integrazione di GitHub