Crear aplicaciones móviles con React.js y Capacitor

En este tutorial, te guiaré a través de la creación de una aplicación móvil utilizando React y Capacitor. Al final, sabrás cómo transformar una aplicación web de React.js en una aplicación móvil nativa con Capacitor, y agregar un sentimiento nativo con Capgo Navegación nativa y transiciones.

Capacitor permite la fácil transformación de tu aplicación web de React.js en una aplicación móvil nativa, sin necesidad de realizar cambios sustanciales o aprender nuevas estrategias como React Native.

El proceso implica unos pocos pasos simples, y antes de que lo sepas, tu aplicación de React.js será una aplicación móvil funcional. Así que mantente aquí mientras te guío en este viaje.

Capacitor en resumen

CapacitorJS es un cambio de juego. Puede integrarse de manera fluida con cualquier proyecto web y envolver su aplicación en una vista web nativa mientras genera el proyecto Xcode y Android Studio nativo. Además, a través de sus plugins, puede acceder a características de dispositivos nativos como la cámara a través de un puente JS.

Capacitor ofrece una forma sencilla de crear una aplicación móvil nativa sin ningún problema o curva de aprendizaje pronunciada. Su API y funcionalidad simplificada lo hacen fácil de incorporar en su proyecto.

Configuración de la Aplicación de React.js

Vamos a utilizar el método más sencillo para iniciar una aplicación de React. Utilizaremos el npm para crear una nueva aplicación de React:

npx create-react-app my-app

Para transformar nuestro proyecto en una aplicación móvil nativa, se requiere una exportación de nuestra aplicación.

Volveremos a esto en un momento. Primero, debemos entender cómo integrar Capacitor en nuestra aplicación de React.

Integración de Capacitor en la Aplicación de React.js

Los pasos de configuración inicial pueden ser un poco detallados, pero después de eso, actualizar el wrapper de la aplicación nativa se vuelve tan simple como ejecutar un sync comando.

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

Instalaremos a continuación el paquete principal y los paquetes relevantes para las plataformas iOS y Android.

Finalmente, agregaremos 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 el Android

las carpetas ahora están presentes en tu proyecto de React.js. Para acceder al proyecto de Android más adelante, instalaAndroid Studio . Para iOS, necesitas un Mac y debes instalar.

Xcode carpetaWeb en su capacitor.config.json como se muestra a continuación:

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

Ejecuta el comando de compilación y sincroniza tu proyecto con Capacitor:

npm run build
npx cap sync

La npm run build comando compilará tu proyecto de React.js, mientras que npx cap sync se alineará la web code en los lugares precisos de las plataformas nativas para que puedan ejecutarse en una aplicación.

Ahora, con un poco de suerte y sin errores, tu aplicación de React.js debería estar lista para su lanzamiento en un dispositivo!

Crear y Desplegar Aplicaciones Nativas

Desarrollar aplicaciones iOS requiere Xcodey Android necesitan Android Studio. Si planea distribuir su aplicación en la tienda de aplicaciones, debe inscribirse en el Apple Developer Program para iOS y el 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 que sus proyectos nativos estén configurados, desplegar su aplicación a un dispositivo conectado es un proceso sencillo.

Para Android Studio, espere a que todo se cargue y luego despliegue su aplicación a un dispositivo conectado.

Para Xcode, establezca su cuenta de firma para desplegar su aplicación a un dispositivo real en lugar del simulador. Después de hacerlo, simplemente presione play para ejecutar la aplicación en su dispositivo conectado, que puede elegir en la parte superior.

Si todo ha ido bien, habrá convertido su aplicación web de React.js en una aplicación móvil nativa!

Capacitor Live Reload

Los marcos de desarrollo modernos suelen venir con hot reload, y afortunadamente, puede tener lo mismo con Capacitor pero en su dispositivo móvil!

Puede hacer que su aplicación alojada localmente esté accesible con live reload en su red al tener la aplicación Capacitor cargar el contenido desde una URL específica.

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

Después de esto, instruye a Capacitor a cargar la aplicación directamente desde el servidor agregando 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 utilizar la IP y el puerto precisos. Ejecuta npx cap copy para aplicar estos cambios a nuestro proyecto nativo.

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

Tenga en cuenta que si se instalan nuevos plugins, como la cámara, es necesario reconstruir tu proyecto nativo. Esto se debe a que los archivos nativos habrán cambiado y no pueden ser actualizados en tiempo real.

Usando Capacitor Plugins

Vamos a echar un vistazo rápido a cómo utilizar un plugin de Capacitor. Vamos a instalar uno simple, el plugin de Compartirque desencadena el diálogo de compartir nativo:

npm i @capacitor/share

Para utilizarlo, importe el paquete y llame a la función correspondiente desde nuestra aplicación. Considerar el share() App.js Después de instalar un nuevo plugin, recuerde sincronizar su proyecto de React nuevamente utilizando:

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;

Ahora puede hacer que la aplicación se sienta más nativa en iOS y Android con la navegación y las transiciones de __CAPGO_KEEP_0__ y solucione problemas de diseño comunes de iOS que causan desbordamiento horizontal o áreas de seguridad recortadas. npx cap sync.

Interfaz de usuario que se siente nativa con Capgo Navegación y Transiciones Nativas

Native-feeling UI with Capgo Native Navigation and Transitions

Ionic para crear aplicaciones de múltiples plataformas, pero integrarla con React es engorrosa y raramente vale la pena cuando ya tiene Tailwind CSS Para un sentir móvil nativo en una aplicación de React + __CAPGO_KEEP_0__, utilice los plugins de __CAPGO_KEEP_1__ en lugar de los kits de interfaz de usuario web solo como Konsta UI:.

For a native mobile feel in a React + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

• @capgo/capacitor-navegación nativa — barra de navegación nativa, Liquid Glass de pestañas en iOS, y un estilo de pestañas difuminado en Android. Su router de React mantiene el estado de ruta; el plugin posee el navegador nativo.
• @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso de swipe de iOS en la capa de WebView, sin adoptar la interfaz de usuario de Ionic.

Instale ambos:

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

Configure la navegación nativa con el modo de inserción de CSS 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',
  },
});

Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propia del sistema; Android utiliza un fondo difuminado de WebView):

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}`);
});

Agregue transiciones de página nativas en su concha de aplicación:

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

Envuelva las páginas de ruta en cap-router-outlet, cap-page, y cap-contento setDirection('forward') o setDirection('back') antes de navegar. No duplique los encabezados o pie de página web cuando la navegación nativa se encarga de esas superficies.

Consulte las guías completas: Usando @capgo/capacitor-navegación-nativa y Usando @capgo/capacitor-transiciones.

Áreas seguras con Tailwind

Para áreas seguras de dispositivos en Tailwind CSS, utilice @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";

Utiliza herramientas como pt-safe, pb-safe, y px-safe en lugar de agregarlos env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de React, abre una solicitud de revisión en GitHub.

Corrección de problemas de diseño de iOS (Viewport, Área Segura y Desbordamiento Horizontal)

Si el contenido parece recortado, desplazado o desplazable horizontalmente en iOS, agregar más overflow-x: hidden o ajustar la etiqueta de viewport sola no suele solucionar el problema. Trabaja a través de estos controles en orden.

Asegúrate de que la etiqueta meta de viewport esté aplicada correctamente

Agrega la etiqueta meta de viewport en index.html dentro de <head>:

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

Gestiona el área segura de iOS desde un solo contenedor raíz

Crear una caja de aplicación única y aplicar allí el relleno de área seguro — no en componentes anidados múltiples:

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-shellEl relleno de área seguro duplicado en encabezados, modales y wrappers de diseño a menudo hace que la interfaz de usuario se vea recortada o demasiado grande.

Con @capgo/tailwind-capacitorpuedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa caja única.

Establecer Capacitor iOS contentInset en never context: Página/área: Página de actualizaciones en vivo. Rol: Etiqueta de UI corta o elemento de navegación. Clave de mensaje `live_update_dynamic_label_to` (Etiqueta de actualización en vivo dinámica a).

primero capacitor.config.tsEn el cual, prefiere el relleno de área nativo deshabilitado y deja que CSS (o la navegación nativa) contentInsetMode: 'css'Propietario del área segura:

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

Mezclar el contenido automático de Capacitor con CSS env(safe-area-inset-*) La aplicación de relleno de padding es una causa común de espaciado doble.

Encuentre el elemento que está desbordando en realidad.

El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screen, un ancho de píxel fijo, o un contenedor muy ancho — no el meta de la etiqueta de viewport en sí. min-width.

Sustituir

[...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,
  }));

por w-screen cuando sea posible. Muchos problemas de desbordamiento horizontal provienen de w-full , relleno de área segura duplicado, o un contenedor de ancho fijo — no de la etiqueta de meta de viewport en sí. 100vw / w-screenSafari Web Inspector, ejecutar:

Conclusion

Capacitor ofrece una forma fluida de crear aplicaciones nativas basadas en un proyecto web existente, proporcionando una forma sencilla de compartir code y tener una interfaz de usuario consistente.

Gracias a tecnologías como Capacitor, nunca ha sido más fácil crear aplicaciones móviles a partir de aplicaciones web de React.js. Eleva tus habilidades en desarrollo web al siguiente nivel creando impresionantes aplicaciones móviles nativas. ¡Disfruta codificando!

Para obtener más información sobre cómo acelerar tu proceso de desarrollo de aplicaciones regístrate en una cuenta gratuita hoy.

Sigue adelante desde Crear aplicaciones móviles con React.js puro y Capacitor

Si estás utilizando Crear aplicaciones móviles con React.js puro y Capacitor para planificar el comportamiento de medios y la interfaz nativa, conecta con Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades en vivo para el detalle de implementación en @capgo/capacitor-actividades en vivo Usando @capgo/capacitor-reproductor de video para la capacidad nativa en Usando @capgo/capacitor-reproductor de video @capgo/capacitor-reproductor de video para el detalle de implementación en @capgo/capacitor-reproductor de video, y Usando @capgo/capacitor-navegación nativa para la capacidad nativa en Usando @capgo/capacitor-navegación nativa.