Build a Next.js Mobile App from Scratch with Capacitor 8

Introduzione

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

Con __CAPGO_KEEP_0__ 8, puoi creare app mobili native per iOS e Android senza scrivere codice nativo.

Al termine di questo tutorial, avrai un'app mobile funzionante che esegue su simulatori e puoi continuare a svilupparla e pubblicarla infine sullo Store App e Google Play. Tempo richiesto:

~30 minuti

• Cosa costruirai:
• Un nuovo progetto Next.js 15 con App Router
• Configurazione di esportazione statica per la mobilità con Capacitor 8 con plugin essenziali
• Applicazioni iOS e Android native
• Impostazione di sviluppo con reload in tempo reale

Hai già un'app Next.js? Ecco Converti la tua app Next.js 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 (disponibile solo su macOS, per lo sviluppo di iOS)
• Android Studio (per lo sviluppo di Android)

Passo 1: Crea un nuovo progetto Next.js

Inizia creando un progetto Next.js 15 fresco:

bunx create-next-app@latest my-mobile-app

Quando viene richiesto, seleziona queste opzioni:

• TypeScript: Sì (consigliato)
• ESLint: Sì
• Tailwind CSS: Sì (consigliato per la personalizzazione di mobile)
• src/ directory: Sì
• App Router: Sì (consigliato)
• Alias di importazione: Predefinito (@/*)

Vai al tuo progetto:

cd my-mobile-app

Passo 2: Configura Next.js per l'esportazione statica

Capacitor richiede file HTML/JS/CSS statici. Configura Next.js per l'esportazione statica aggiornando next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

Perché questi impostazioni?

• output: 'export' — Genera HTML statico invece di richiedere un server Node.js
• images: { unoptimized: true } — Disabilita l'ottimizzazione delle immagini di Next.js (richiede un server)
• trailingSlash: true — Assicura la routing corretta nella WebView nativa

Step 3: Aggiungi script mobili

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

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Testa la build:

bun run build

Devi vedere un out directory con i tuoi file statici.

Step 4: Installa Capacitor 8

Installa i pacchetti core di Capacitor:

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

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

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

Di cosa fanno questi plugin:

• @capacitor/app — Eventi di ciclo di vita dell'applicazione (in primo piano/ in background, collegamenti profondi)
• @capacitor/tastiera — 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 di valori chiave (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 out

Sostituisci:

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

Questa crea capacitor.config.ts. Aggiorna con la configurazione del plugin:

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

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

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

Questa 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. Seleziona un simulatore dal menu a discesa dei dispositivi
2. Clicca sul pulsante Play 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 Run o premi Shift + F10

Passo 8: Configura Live Reload

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

1. Trova l'indirizzo IP locale:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. Creare una configurazione di sviluppo Capacitor. Aggiungi a capacitor.config.ts:

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

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  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: 'out',
  plugins: {
    // ... same plugin config
  },
};

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

export default config;

3. Inizia il server di sviluppo e copia la configurazione in nativo:

bun run dev &
NODE_ENV=development bunx cap copy

4. Riavvia in Xcode/Android Studio

Ora le modifiche al tuo Next.js code si ricollegheranno automaticamente sul dispositivo.

Passo 9: Crea la Prima Schermata Mobile

Creiamo una semplice schermata di home adatta ai dispositivi mobili. Aggiorna src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

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

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="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">
          Learn More
        </button>
      </div>
    </main>
  );
}

Passo 10: Aggiungi Gestione Area Sicura

I dispositivi mobili hanno notch, indicatori di home e barre di stato. Aggiungi la gestione dell'area sicura con Tailwind.

Aggiorna src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

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

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

Struttura del Progetto

Il tuo progetto dovrebbe ora avere questo aspetto:

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

Passaggi Successivi

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

Configurazione essenziale

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

Aggiungi più funzionalità

• Camera: bun add @capacitor/camera
• Posizione geografica: bun add @capacitor/geolocation
• Informazioni di notifica push: bun add @capacitor/push-notifications
• Sistema di file: bun add @capacitor/filesystem

Interfaccia utente nativa e transizioni

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

• @capgo/capacitor-navigazione-nativa – barra dei pulsanti Liquido 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 Utilizzando @capgo/capacitor-navigazione nativa, Utilizzando @capgo/capacitor-transizioni, e il repo tailwind-capacitor per la configurazione specifica di Next.js.

Risolvere i Problemi di Layout iOS (Viewport, Area di Sicurezza, e Scoramento Orizzontale)

Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere o modificare il tag viewport da solo non risolve di solito il problema. Lavora attraverso questi controlli in ordine. overflow-x: hidden Assicurati che il tag meta viewport sia applicato correttamente

Router dell'App

export (app/da viewport Risolvere i Problemi di Layout iOS (Viewport, Area di Sicurezza, e Scoramento Orizzontale) è un problema comune quando si sviluppano applicazioni mobili con Next.js e Capacitor. Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere o modificare il tag viewport da solo non risolve di solito il problema. Lavora attraverso questi controlli in ordine. app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

Router delle pagine (pages/inserisci l'etichetta meta per il viewport pages/_app.tsxnon _document.tsx.

Gestisci l'area sicura di iOS da un wrapper radice solo

Crea un unico contenitore per l'applicazione e applica il padding dell'area sicura lì — non nei componenti nidificati multipli:

html,
body,
#__next {
  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 padding dell'area sicura duplicato nei titoli, nelle finestre modal e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande.

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

Imposta Capacitor iOS contentInset Inizia never primo

Sul capacitor.config.ts, preferisci l'ingombro 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: 'out',
  ios: {
    contentInset: 'never',
  },
};

Mescolare l'ingombro automatico di contenuto di Capacitor con CSS env(safe-area-inset-*) è una causa comune di doppia interlinea.

Trova l'elemento che sta effondando realmente

L'elemento colpevole è spesso un elemento che utilizza 100vw, Tailwind w-screen, una larghezza fissa in pixel, o un grande min-width.

Sul 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

Costruisci con fallimento con 'Non è possibile trovare modulo' Esegui bun install e riprova.

iOS: “Identità di firma non trovata” Apri 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 le modifiche. Verifica l'indirizzo IP per il live reload e assicurati che il server di sviluppo sia in esecuzione.

Risorse

• Capacitor 8 Documentazione
• Documentazione di Next.js 15
• Capgo - Aggiornamenti in tempo reale
• @capgo/capacitor-navigazione nativa
• @capgo/capacitor-transizioni
• @capgo/tailwind-capacitor

Siete pronti a spedire la vostra app? Imparate come Capgo può aiutarvi a consegnare aggiornamenti più velocemente — iscrivetevi a un account gratuito oggi.

Continuate da Costruire un'app mobile Next.js da zero con Capacitor 8

Se state utilizzando Costruire un'app mobile Next.js da zero con Capacitor 8 per pianificare l'automazione CI/CD, connettetelo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Costruzioni native Capgo per il workflow del prodotto in Costruzioni native Capgo Capgo Integrazioni per il workflow del prodotto in Capgo Integrazioni Integrazione CI/CD per la dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione azioni per la dettaglio di implementazione in GitHub Integrazione azioni