Construye una aplicación móvil de Next.js desde cero con Capacitor 8

Introducción

¿Quieres crear una aplicación móvil con Next.js desde la base? Esta guía te guía a través de la creación de un proyecto de Next.js 15 configurado para móvil desde el principio, luego empaquetarlo como aplicaciones móviles nativas de iOS y Android utilizando Capacitor 8.

Al final de este tutorial, tendrás una aplicación móvil en funcionamiento en simuladores que puedes seguir desarrollando y eventualmente publicar en la Tienda de App y Google Play.

Tiempo requerido: ~30 minutos

¿Qué construirás:

Un nuevo proyecto de Next.js 15 con App Router
Configuración de exportación estática para móviles
Capacitor 8 con plugins esenciales
Aplicaciones nativas de iOS y Android
Configuración de desarrollo con live reload

Ya tienes una aplicación de Next.js? Consulta Convierte tu aplicación de Next.js a móvil en su lugar.

Requisitos previos

Asegúrese de tener instalados estos:

Node.js 18+ (verifique con node --version)
Bun administrador de paquetes (curl -fsSL https://bun.sh/install | bash)
Xcode (solo para macOS, para desarrollo de iOS)
Android Studio (para desarrollo de Android)

Paso 1: Crear un Nuevo Proyecto de Next.js

Comience creando un proyecto de Next.js 15 fresco:

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

Cuando se le pregunte, seleccione estas opciones:

TypeScript: Sí (recomendado)
ESLint: Sí
Tailwind CSS: Sí (recomendado para estilos de móvil)
src/ carpeta: Sí
App Router: Sí (recomendado)
Alias de importación: Predeterminado (@/*)

Navegue a su proyecto:

cd my-mobile-app

Paso 2: Configure Next.js para Exportación Estática

Capacitor requiere archivos HTML/JS/CSS estáticos. Configure Next.js para la exportación estática actualizando 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;

¿Por qué estos ajustes?

output: 'export' — Genera HTML estático en lugar de requerir un servidor Node.js
images: { unoptimized: true } — Desactiva la Optimización de Imágenes de Next.js (requiere un servidor)
trailingSlash: true — Asegura la ruta correcta en la WebView nativa

Paso 3: Agregar scripts móviles

Actualice su package.json con scripts de desarrollo móvil:

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

Pruebe la compilación:

bun run build

Debería ver un out directorio con tus archivos estáticos.

Paso 4: Instala Capacitor 8

Instala los paquetes de núcleo de Capacitor:

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

Instala plugins esenciales que la mayoría de las aplicaciones móviles necesitan:

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

¿Qué hacen estos plugins:

@capacitor/app — Eventos de ciclo de vida de la aplicación (anterior/plano, enlaces profundos)
@capacitor/keyboard — Controla el comportamiento del teclado
@capacitor/splash-screen — Control de pantalla de bienvenida nativa
@capacitor/status-bar — Establecer el estilo de la barra de estado del dispositivo
@capacitor/preferencias — Almacenamiento de valores clave (como localStorage pero nativo)

Paso 5: Inicializar Capacitor

Inicialice Capacitor con los detalles de su proyecto:

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

Sustituir:

"My Mobile App" con el nombre de pantalla de su aplicación
com.example.mymobileapp con el ID de la aplicación (notación de dominio inverso)

Esto crea capacitor.config.tsActualice con la configuración 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;

Paso 6: Agregar Plataformas Nativas

Instale los paquetes de plataforma:

bun add @capacitor/ios @capacitor/android

Genera los proyectos nativos:

bunx cap add ios
bunx cap add android

Esto crea ios y android los directorios que contienen los proyectos nativos.

Paso 7: Compilar y Ejecutar

Compila tu proyecto y sincroniza con las plataformas nativas:

bun run mobile

Abrir en iOS Simulator:

bun run mobile:ios

O Android Emulator:

bun run mobile:android

En Xcode (iOS):

Selecciona un simulador desde el menú de dispositivos
Haz clic en el botón de reproducción o presiona Cmd + R

En Android Studio:

Espera a que Gradle termine sincronizando
Seleccione un emulador desde el menú de dispositivos
Haga clic en el botón Ejecutar o presione Shift + F10

Paso 8: Configura Live Reload

Para un desarrollo más rápido, habilite Live Reload para que los cambios se reflejen instantáneamente en tu dispositivo.

Encuentra tu dirección IP local:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Crea una configuración de desarrollo Capacitor. Agrega 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;

Inicia el servidor de desarrollo y copia la configuración a nativo:

bun run dev &
NODE_ENV=development bunx cap copy

Reconstruye en Xcode/Android Studio

Ahora los cambios en tu Next.js code se recargarán automáticamente en el dispositivo.

Paso 9: Crea tu primera pantalla móvil

Vamos a crear una pantalla de inicio móvil simple y amigable. Actualiza 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>
  );
}

Paso 10: Agregar manejo de área segura

Los dispositivos móviles tienen ranuras, indicadores de inicio y barras de estado. Agregue el manejo de área segura con Tailwind.

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

Estructura del Proyecto

Su proyecto debería verse así:

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
└── ...

Pasos siguientes

Ahora tiene una aplicación móvil de Next.js en funcionamiento. Aquí está qué hacer a continuación:

Configuración básica

Iconos de la aplicación: Reemplazar los iconos predeterminados en y ios/App/App/Assets.xcassets Pantalla de bienvenida: Reemplazar la pantalla de bienvenida predeterminada android/app/src/main/res
Reemplazar la pantalla de bienvenida predeterminada Personalice en proyectos nativos o utilice @capacitor/splash-screen config
Enlaces Profundos: Configure los esquemas de URL para tu aplicación

Agregar Más Características

Cámara: bun add @capacitor/camera
Ubicación: bun add @capacitor/geolocation
Notificaciones Push: bun add @capacitor/push-notifications
Sistema de Archivos: bun add @capacitor/filesystem

Mejora de la Interfaz de Usuario

Considera agregar Konsta UI para componentes que se ven nativos en iOS/Android:

bun add konsta

Actualizaciones a través de Internet

Configuración Capgo para enviar actualizaciones sin tener que volver a enviar la aplicación a la tienda:

bunx @capgo/cli init

Solución de problemas

La compilación falla con “No se puede encontrar el módulo” Ejecutar bun install y vuelve a intentarlo.

iOS: “No se encontró identidad de firma” Abre Xcode, ve a Firmas y Capabilities, y selecciona tu equipo de desarrollo.

Android: “SDK no se encontró en la ubicación” Crear android/local.properties con sdk.dir=/path/to/android/sdk

Los cambios no se muestran en el dispositivo Asegúrate de haber ejecutado bun run mobile después de hacer cambios. Para el recarga en vivo, verifica que la dirección IP es correcta y el servidor de desarrollo está en ejecución.

Recursos

¿Listo para enviar tu aplicación? Aprende cómo Capgo puede ayudarte a entregar actualizaciones más rápido — regístrate para una cuenta gratuita hoy.

Crea una aplicación móvil de Next.js desde cero con Capacitor 8