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

Introduzione

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

Al termine di questa guida, 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 Next.js 15 con App Router
Configurazione di esportazione statica per la mobilità
Capacitor 8 con plugin essenziali
Applicazioni native iOS e Android
Impostazione di sviluppo con reload in tempo reale

Hai già un'app Next.js? Ecco Converti la tua app Next.js in mobile invece.

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 Next.js

Inizia creando un progetto Next.js 15 fresco:

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

Quando richiesto, seleziona queste opzioni:

TypeScript: Sì (consigliato)
ESLint: Sì
Tailwind CSS: Sì (consigliato per la personalizzazione mobile)
src/ directory: Sì
App Router: Sì (consigliato)
Import alias: Predefinito (@/*)

Naviga 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

Passo 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

Dovresti vedere un out directory con i tuoi file statici.

Passo 4: Installa Capacitor 8

Installa i pacchetti core di Capacitor:

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

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

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'applicazione (in primo piano/secondo piano, collegamenti profondi)
@capacitor/keyboard — Controllo del comportamento della tastiera
@capacitor/splash-screen — Controllo dello schermo di benvenuto nativo
@capacitor/status-bar — Personalizzazione della barra dello stato del dispositivo
@capacitor/preferences — Archiviazione dei valori chiave (come localStorage ma nativa)

Passo 5: Inizializza Capacitor

Inizia Capacitor con i dettagli del tuo progetto:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

Sostituisci con il nome visualizzato dell'app

"My Mobile App" con l'ID dell'app (notazione di dominio inverso)
com.example.mymobileapp Ciò crea

. Aggiornalo con la configurazione del plugin: capacitor.config.tsPasso 6: Aggiungi piattaforme native

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;

Installa i pacchetti delle piattaforme:

Genera i progetti nativi:

bun add @capacitor/ios @capacitor/android

Ciò crea

bunx cap add ios
bunx cap add android

e ios directory contenenti i progetti nativi. android Passo 7: Compila e Esegui

Sostituisci con il nome visualizzato dell'app

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 dalla casella a discesa dei dispositivi
Clicca sul pulsante Play o premi Cmd + R

In Android Studio:

Aspetta che Gradle finisca di sincronizzare
Seleziona un emulatore dalla casella a discesa dei dispositivi
Clicca sul pulsante Run o premi Shift + F10

Passo 8: Configura Live Reload

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

Trova l'indirizzo IP locale:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

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

Avvia il server di sviluppo e copia la configurazione nativa:

bun run dev &
NODE_ENV=development bunx cap copy

Riavvia in Xcode/Android Studio

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

Passo 9: Crea la Prima Schermata Mobile

Creiamo una semplice schermata di benvenuto 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 avvio personalizzato: Personalizza in 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
Geolocalizzazione: bun add @capacitor/geolocation
Notifiche Push: bun add @capacitor/push-notifications
Sistema di File: bun add @capacitor/filesystem

Miglioramento dell'interfaccia utente

Considera di aggiungere Konsta UI per componenti iOS/Android che assomigliano a quelli nativi:

bun add konsta

Aggiornamenti Over-the-Air

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

bunx @capgo/cli init

Risoluzione dei Problemi

Il build fallisce con “Cannot find module” Esegui bun install e riprova.

iOS: “Non è stato trovato alcun identità di firma” 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

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

Risorse

Siete pronti a distribuire il vostro'applicazione? Scoprite come Capgo possa aiutarvi a consegnare gli aggiornamenti più velocemente — iscrivetevi a un account gratuito oggi.

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

Introduzione

Requisiti

Passo 1: Crea un nuovo progetto Next.js

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

Passo 3: Aggiungi script mobili

Passo 4: Installa Capacitor 8

Passo 5: Inizializza Capacitor

Installa i pacchetti delle piattaforme:

Sostituisci con il nome visualizzato dell'app

Passo 8: Configura Live Reload

Passo 9: Crea la Prima Schermata Mobile

Passo 10: Aggiungi Gestione Area Sicura

Struttura del Progetto

Passaggi successivi

Configurazione essenziale

Aggiungi più funzionalità

Miglioramento dell'interfaccia utente

Aggiornamenti Over-the-Air

Risoluzione dei Problemi

Risorse