Saltar al contenido principal
Tutorial

Crear apps móviles con React.js puro y Capacitor

Una guía sobre cómo transformar una aplicación web de React.js en una app móvil nativa utilizando Capacitor, y añadiendo Capgo Native Navigation, Transitions y las mejores prácticas de diseño para iOS.

Ilustración del blog: crear apps móviles con React.js puro y Capacitor Capgo

Este tutorial te guiará para crear una app móvil usando React y Capacitor. Al terminar, sabrás cómo transformar una web app de React.js en una app móvil nativa con Capacitor, y añadir un toque nativo con Capgo Native Navigation and Transitions.

Capacitor permite transformar fácilmente tu web app de React.js en una app móvil nativa, sin necesidad de cambios profundos ni de aprender nuevas estrategias como React Native.

El proceso consta de unos pocos pasos sencillos y, antes de que te des cuenta, tu app de React.js será una aplicación móvil totalmente funcional. Así que, quédate con nosotros mientras te guiamos en este proceso.

Resumen de Capacitor

CapacitorJS cambia las reglas del juego. Se integra perfectamente con cualquier proyecto web y envuelve tu app en un webview nativo mientras genera el proyecto nativo de Xcode y Android Studio. Además, con sus plugins puedes acceder a funciones nativas del dispositivo, como la cámara, mediante un puente JS.

Capacitor ofrece una forma sencilla de crear una app móvil nativa sin complicaciones ni una curva de aprendizaje pronunciada. Su simple API y su funcionalidad optimizada facilitan integrarlo en tu proyecto.

Configurar tu app de React.js

Vamos con el método más sencillo para iniciar una app React. Usaremos el gestor de paquetes npm para crear una nueva app React:

npx create-react-app my-app

Para transformar nuestro proyecto en una app móvil nativa, se necesita un Exportar de nuestra app es necesario.

Volvemos a esto en un momento. Primero, veamos cómo integrar Capacitor en nuestra app de React.

Integración de Capacitor en tu app React.js

Los pasos de configuración inicial pueden ser un poco detallados, pero después, actualizar el wrapper de tu app nativa es tan simple como ejecutar un sync comando.

Primero, instalaremos Capacitor CLI como dependencia de desarrollo y lo configuraremos en nuestro proyecto. Durante la configuración, acepta los valores predeterminados para el nombre y el bundle ID presionando “enter”.

A continuación, instalaremos el paquete principal y los paquetes correspondientes para las plataformas iOS y Android.

Finalmente, añadiremos las plataformas, y Capacitor creará carpetas para cada plataforma en la raíz de nuestro proyecto:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your React project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

El iOS y Android los directorios ya están presentes en tu proyecto de React.js.

Para acceder al proyecto de Android más adelante, instala Android Studio. Para iOS, necesitas un Mac y debes instalar Xcode.

A continuación, actualiza el webDir en tu archivo capacitor.config.json archivo como se muestra a continuación:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "build",
  "bundledWebRuntime": false
}

Ejecuta el comando de build y sincroniza tu proyecto con Capacitor:

npm run build
npx cap sync

El npm run build el comando compilará tu proyecto de React.js, mientras que npx cap sync alineará el code web en los lugares correctos de las plataformas nativas para que pueda ejecutarse en la app.

Ahora, con un poco de suerte y sin errores, tu app de React.js debería estar lista para lanzarse en un dispositivo.

Build y despliegue de tus apps nativas

Desarrollar apps para iOS requiere Xcode, y las apps de Android necesitan Android Studio. Si planeas distribuir tu app en la tienda de aplicaciones, debes inscribirte en el Apple Developer Program para iOS y en Google Play Console para Android.

El Capacitor CLI simplifica el proceso de abrir ambos proyectos nativos:

npx cap open ios
npx cap open android

Una vez configurados tus proyectos nativos, desplegar tu app en un dispositivo conectado es un proceso sencillo.

En Android Studio, espera a que todo cargue y luego despliega tu app en un dispositivo conectado.

En Xcode, configura tu cuenta de firma para desplegar tu app en un dispositivo real en lugar de solo el simulador. Después, simplemente pulsa play para ejecutar la app en el dispositivo conectado, que puedes elegir en la parte superior.

Si todo ha salido bien, ¡habrás convertido tu web app de React.js en una aplicación móvil nativa!

Live Reload con Capacitor

Los frameworks de desarrollo modernos suelen incluir hot reload, y por suerte, puedes tener lo mismo con Capacitor pero en tu dispositivo móvil!

Puedes hacer que tu aplicación local sea accesible con live reload en tu red haciendo que la app Capacitor cargue el contenido desde una URL específica.

Primero, determina tu dirección IP local. En una Mac, puedes hacerlo ejecutando ipconfig getifaddr en0 en la terminal. En Windows, ejecuta ipconfig y busca la dirección IPv4.

Después, indica a Capacitor que cargue la app directamente desde el servidor añadiendo otro parámetro a tu capacitor.config.ts archivo:

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'build',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

Asegúrate de usar la IP y el puerto correctos. Ejecuta npx cap copy para aplicar estos cambios a nuestro proyecto nativo.

Al desplegar tu app una vez más a través de Android Studio o Xcode, cualquier cambio en tu app de React se recargará y mostrará automáticamente en tu app.

Ten en cuenta que si se instalan nuevos plugins, como el de cámara, es necesario reconstruir tu proyecto nativo. Esto se debe a que los archivos nativos habrán cambiado y no pueden actualizarse al vuelo.

Uso de Capacitor Plugins

Echemos un vistazo rápido a cómo usar un plugin de Capacitor. Instalemos uno sencillo, el plugin Share, que muestra el diálogo de compartir nativo:

npm i @capacitor/share

Para usarlo, importa el paquete y llama a la función correspondiente share() desde nuestra app. Considera el App.js:

import { Share } from '@capacitor/share';

function ShareButton() {
  const share = async () => {
    await Share.share({
      title: 'React App',
      text: 'Visit this React App',
      url: 'http://localhost:3000',
      dialogTitle: 'Share with...'
    });
  };

  return (
    <button onClick={share}>
      Share
    </button>
  );
}

export default ShareButton;

Después de instalar un nuevo plugin, recuerda sincronizar tu proyecto de React de nuevo usando npx cap sync.

Después, puedes hacer que la app se sienta más nativa en iOS y Android con la navegación y las transiciones de Capgo, y solucionar problemas comunes de layout en iOS que causan desbordamiento horizontal o áreas seguras recortadas.

UI con sensación nativa, navegación y transiciones nativas de Capgo

He trabajado durante años con Ionic para crear aplicaciones multiplataforma, pero integrarlo con React es un hack y rara vez vale la pena cuando ya tienes Tailwind CSS.

Para una sensación nativa móvil en una app de React + Capacitor, usa plugins de Capgo en lugar de kits de UI solo web como Konsta UI:

  • @capgo/capacitor-native-navigation — navbar nativa, tab bar estilo Liquid Glass en iOS y un estilo de tab bar con desenfoque en Android. Tu React router mantiene el estado de las rutas; el plugin se encarga del chrome nativo.
  • @capgo/capacitor-transitions — transiciones de página estilo Ionic y swipe-back desde el borde en iOS en la capa WebView, sin adoptar Ionic UI.

Instala ambos:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Configura la navegación nativa con CSS inset mode para que el contenido web respete las barras nativas:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Renderiza una tab bar Liquid Glass (iOS usa renderizado del sistema; Android usa un fondo WebView con desenfoque):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  navigate(`/${id}`);
});

Añade transiciones de página nativas en tu app shell:

import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

export function AppShell() {
  const navigate = useNavigate();
  const outletRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (outletRef.current) {
      setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
    }
  }, []);

  const openSettings = () => {
    setDirection('forward');
    navigate('/settings');
  };

  return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}

Envuelve las páginas enrutadas en cap-router-outlet, cap-page, y cap-content, y llama a setDirection('forward') o setDirection('back') antes de navegar. No dupliques headers o footers web si la navegación nativa ya gestiona esas áreas.

Consulta las guías completas: Uso de @capgo/capacitor-native-navigation y Uso de @capgo/capacitor-transitions.

Safe areas con Tailwind

Para las safe areas del dispositivo en Tailwind CSS, usa @capgo/tailwind-capacitor (publicado como tailwind-capacitor en npm). Proporciona safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor:

bun add -D tailwind-capacitor

En src/index.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Usa utilidades como pt-safe, pb-safe, y px-safe en lugar de añadir env(safe-area-inset-*) a mano. El proyecto se desarrolla activamente; si falta algo para tu configuración de React, abre un PR en GitHub.

Cómo solucionar problemas de layout en iOS (viewport, safe area y overflow horizontal)

Si el contenido se ve recortado, desplazado o con scroll horizontal en iOS, añadir más overflow-x: hidden o ajustar solo la etiqueta viewport no suele solucionarlo. Revisa estas comprobaciones en orden.

Asegúrate de que la meta tag viewport esté bien aplicada

Añade la etiqueta meta viewport en index.html dentro del <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

Gestiona el safe area de iOS desde un único wrapper raíz

Crea un único app shell y aplica el padding de safe area ahí, no en múltiples componentes anidados:

html,
body,
#root {
  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);
}

Envuelve todo el contenido de la página dentro de .app-shell. El padding de safe-area duplicado en headers, modales y wrappers de layout suele hacer que la UI parezca recortada o demasiado grande.

Con @capgo/tailwind-capacitor, puedes aplicar el mismo padding usando utilidades como pt-safe pb-safe px-safe en ese único shell.

Configura Capacitor iOS contentInset a never primero

En capacitor.config.ts, prefiere desactivar el inset nativo y dejar que CSS (o la navegación nativa) contentInsetMode: 'css') se encargue del safe area:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'build',
  ios: {
    contentInset: 'never',
  },
};

Combinar el content inset automático de Capacitor con CSS env(safe-area-inset-*) es una causa común de espaciado doble.

Encuentra el elemento que realmente desborda

El culpable habitual es un elemento que usa 100vw, Tailwind w-screen, un ancho fijo en píxeles, o un min-width.

En Safari Web Inspector, ejecuta:

[...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, reemplaza w-screen con w-full siempre que sea posible. Muchos problemas de desbordamiento horizontal vienen de 100vw / w-screen, padding de safe-area duplicado o un contenedor de ancho fijo, no del propio meta tag del viewport.

Conclusión

Capacitor ofrece una forma fluida de crear apps nativas a partir de un proyecto web existente, proporcionando una manera sencilla de compartir code y mantener una UI consistente.

Gracias a tecnologías como Capacitor, crear aplicaciones móviles a partir de apps web de React.js nunca había sido tan fácil. Lleva tus habilidades de desarrollo web al siguiente nivel creando impresionantes apps móviles nativas. ¡Feliz codificación!

Para saber más sobre cómo puedes acelerar el proceso de desarrollo de tu app, crea una cuenta gratis hoy.

Sigue leyendo desde Crear apps móviles con React.js puro y Capacitor

Si estás usando Crear apps móviles con React.js puro y Capacitor para planificar el comportamiento de los medios nativos y la interfaz, conéctalo con Uso de @capgo/capacitor-live-activities para la capacidad nativa en Uso de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities para los detalles de implementación en @capgo/capacitor-live-activities, Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player, @capgo/capacitor-video-player por el detalle de implementación en @capgo/capacitor-video-player, y Uso de @capgo/capacitor-native-navigation para la capacidad nativa al usar @capgo/capacitor-native-navigation.

Live updates para apps Capacitor

Cuando un bug de la capa web está en producción, publica el fix a través de Capgo en lugar de esperar días a la aprobación de la app store. Los usuarios reciben la actualización en segundo plano mientras los cambios nativos siguen el flujo de revisión habitual.

Lo último de nuestro blog

Capgo te da la información clave que necesitas para crear una app móvil realmente profesional.