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óviles desde el primer día, luego empaquetándolo como aplicaciones móviles nativas de iOS y Android utilizando Capacitor 8.

Al final de esta tutoría, 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 recarga en vivo

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

Requisitos previos

Asegúrate de tener instalados:

Node.js 18+ (verificar 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 móviles)
src/ directory: Sí
App Router: Sí (recomendado)
Import alias: Por defecto (@/*)

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

Step 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 carpeta con sus archivos estáticos.

Step 4: Instale Capacitor 8

Instale los paquetes de núcleo Capacitor:

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

Instale los 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 — Controlar el comportamiento del teclado
@capacitor/splash-screen — Control de pantalla de bienvenida nativa
@capacitor/status-bar — Estilizar la barra de estado del dispositivo
@capacitor/preferences — Almacenamiento de valor clave (como localStorage pero nativo)

Step 5: Inicializa Capacitor

Inicializa Capacitor con los detalles de tu proyecto:

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

Sustituye:

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

Esto crea capacitor.config.tsActualízalo 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;

Step 6: Agrega Plataformas Nativas

Instala 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 los directorios que contienen los proyectos nativos. android Step 7: Compilar y Ejecutar

Compila tu proyecto y sincroniza con las plataformas nativas:

Abre en iOS Simulator:

bun run mobile

O Android Emulator:

bun run mobile:ios

En Xcode (iOS):

bun run mobile:android

Selecciona un simulador desde el menú de dispositivos

Haz clic en el botón de reproducción o presiona
En Android Studio: Cmd + R

Espera a que Gradle termine de sincronizar

Selecciona un emulador desde el menú de dispositivos
Select a simulator from the device dropdown
Haz clic en el botón Ejecutar o presiona Shift + F10

Paso 8: Configura Live Reload

Para un desarrollo más rápido, habilita el live reload para que los cambios aparezcan instantáneamente en tu dispositivo.

Encuentra tu dirección IP local:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Crea un archivo de 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 simple y móvil. 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: Agrega manejo de área segura

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

Actualización 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 ahora 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 funcionando. Aquí está qué hacer a continuación:

Configuración Básica

Iconos de la Aplicación: Sustituir iconos predeterminados en ios/App/App/Assets.xcassets y android/app/src/main/res
Pantalla de Inicio: Personalizar en proyectos nativos o usar @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 de Puesta en Marcha: bun add @capacitor/push-notifications
Sistema de Archivos: bun add @capacitor/filesystem

Mejora de la Interfaz de Usuario

Considera agregar Konsta UI para componentes iOS/Android que parecen nativos:

bun add konsta

Actualizaciones en Línea:

Configura Capgo para enviar actualizaciones sin la necesidad de volver a presentar la aplicación en la tienda:

bunx @capgo/cli init

Solución de problemas

El proceso de compilación falla con “No se puede encontrar el módulo” Ejecuta 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” Crea android/local.properties con sdk.dir=/path/to/android/sdk

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

Recursos

¿Está listo para enviar su aplicación? Aprenda cómo Capgo puede ayudarlo a entregar actualizaciones más rápido — registrarse para una cuenta gratuita hoy.

Siga adelante desde Construya una aplicación móvil de Next.js desde cero con Capacitor 8

Si estás utilizando Construye una aplicación móvil de Next.js desde cero con Capacitor 8 para planificar la automatización de CI/CD, conecta con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, Integración de CI/CD para el detalle de implementación en Integración de CI/CD, y GitHub Integración de Acciones para los detalles de implementación en GitHub Acciones de Integración.

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