Construye una aplicación móvil de Nuxt desde cero con Capacitor 8

Introducción

¿Quieres crear una aplicación móvil con Nuxt desde cero? Esta guía te guía a través de la creación de un proyecto de Nuxt 4 configurado para móviles desde el principio, 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 Nuxt 4 con la estructura de directorio más reciente
Configuración de generació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 Nuxt? Revisa Convierte tu aplicación de Nuxt a móvil 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 Nuxt 4

Comience creando un proyecto de Nuxt 4 fresco:

bunx nuxi@latest init my-mobile-app
cd my-mobile-app
bun install

Estructura de Directorio de Nuxt 4

Nuxt 4 utiliza una nueva estructura de directorio con app code en el app/ dirección:

my-mobile-app/
  app/
    assets/
    components/
    composables/
    layouts/
    middleware/
    pages/
    plugins/
    utils/
    app.vue
  public/
  server/
  nuxt.config.ts
  package.json

Esta estructura proporciona una mejor separación entre la aplicación y el servidor code.

Paso 2: Configure Nuxt para la Generación Estática

Capacitor requiere archivos HTML/JS/CSS estáticos. Configure Nuxt para la generación estática en nuxt.config.ts:

export default defineNuxtConfig({
  compatibilityDate: '2025-01-15',
  devtools: { enabled: true },

  // Enable static generation
  ssr: true,
  nitro: {
    preset: 'static',
  },
});

Paso 3: Agregar Scripts Móviles

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

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

Pruebe la generación estática:

bun run generate

Debería ver un .output/public directorio con sus archivos estáticos.

Paso 4: Instale Capacitor 8

Instale los paquetes de Capacitor core:

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

Instale 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 — Control del 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 valores clave (como localStorage pero nativo)

Paso 5: Inicialice Capacitor

Inicia Capacitor con los detalles de tu proyecto:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir .output/public

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.tsActualiza con la configuración 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;

Paso 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 android directorios que contienen los proyectos nativos.

Paso 7: Construye y Ejecuta

Construye tu proyecto y sincroniza con plataformas nativas:

bun run mobile

Abrir en Simulador de iOS:

bun run mobile:ios

O Emulador de Android:

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 de sincronizar
Selecciona un emulador desde el menú de dispositivos
Haz clic en el botón de ejecución o presiona Shift + F10

Paso 8: Configura Live Reload

Para un desarrollo más rápido, habilite la recarga en vivo para que los cambios aparezcan instantáneamente en su dispositivo.

Encuentre su dirección IP local:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Cree un archivo de configuración de desarrollo Capacitor. Actualice 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;

Inicie el servidor de desarrollo y copie la configuración a nativo:

bun run dev &
NODE_ENV=development bunx cap copy

Reconstruya en Xcode/Android Studio

Ahora los cambios en su Nuxt code se recargarán automáticamente en el dispositivo.

Paso 9: Crea la primera pantalla móvil

Vamos a crear una pantalla de inicio amigable para móviles. Actualice app/app.vue:

<template>
  <NuxtPage />
</template>

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

Paso 10: Agregue Tailwind CSS

Para que el estilo funcione, agregue Tailwind CSS a su proyecto:

bun add tailwindcss @tailwindcss/vite

Actualice 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()],
  },
});

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

Vamos a implementar la funcionalidad del botón de compartir:

bun add @capacitor/share

Actualizar app/pages/index.vue para utilizar el plugin de Compartir:

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

Sincronizar y reconstruir:

bun run mobile

Estructura del Proyecto

Tu proyecto debería verse así:

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

Pasos Siguientes

Ahora tienes una aplicación móvil de Nuxt funcionando. Aquí te mostramos qué hacer a continuación:

Configuración Esencial

Íconos de la Aplicación: Sustituye iconos por defecto en ios/App/App/Assets.xcassets y android/app/src/main/res
Pantalla de bienvenida: Personaliza en proyectos nativos o utiliza @capacitor/splash-screen configuración
Enlaces Profundos: Configura 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 interfaz de usuario

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

bun add konsta

Luego actualice su CSS para importar el tema:

@import 'tailwindcss';
@import 'konsta/theme.css';

Actualizaciones en Línea

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

bunx @capgo/cli init

Solución de problemas

Los errores de compilación con “No se puede encontrar módulo” Ejecutar bun install y vuelve a intentarlo.

iOS: “No se encontró identidad de firma” Abra Xcode, vaya a Signing & Capabilities, y seleccione su 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úrese de haber ejecutado bun run mobile después de hacer cambios. Para el recarga en vivo, verifique que la dirección IP es correcta y que el servidor de desarrollo está en ejecución.

.output/public está vacío o faltante Asegúrese de haber configurado nitro: { preset: 'static' } en nuxt.config.ts y ejecutar bun run generate.

Recursos

¿Estás 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.

Sigue adelante desde Construye una aplicación móvil de Nuxt desde cero con Capacitor 8

Si estás utilizando Construye una aplicación móvil de Nuxt desde cero con Capacitor 8 para planificar la automatización de CI/CD, conectarla con Capgo automatización de CI/CD para el flujo de trabajo del producto en Capgo automatización de 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 el detalle de implementación en GitHub integración de acciones.

Crea una Aplicación Móvil de Nuxt desde Cero con Capacitor 8