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

Esta tutoría 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 de navegación y transiciones nativas.

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 alteraciones sustanciales o aprendizaje de 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 guiamos en este viaje.

Capacitor - Resumen

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

Capacitor ofrece una forma directa de crear una aplicación móvil nativa sin ningún problema o curva de aprendizaje empinada. Su simple API y funcionalidad escalonada lo hacen fácil de incorporar en tu proyecto.

Configuración de tu aplicación de React.js

Vamos a utilizar el método más simple para iniciar una aplicación de React. Usaremos el administrador de paquetes 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, es export de nuestra aplicación lo que se requiere.

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

Integrando Capacitor en tu aplicación de React.js

Los pasos de configuración inicial pueden ser un poco detallados, pero después de eso, actualizar tu wrapper de 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.”

Siguiente, instalaremos 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

La carpeta ios y android

ahora están presentes en tu proyecto de React.js. Para acceder al proyecto de Android más adelante, instala Android StudioPara iOS, necesitas un Mac y debes instalar Xcode.

A continuación, actualiza el webDir en tu archivo 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á el 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!

Desarrollando y Desplegando Tus Aplicaciones Nativas

Desarrollar aplicaciones iOS requiere Xcode, y las aplicaciones Android necesitan Android Studio. Si planeas distribuir tu aplicación en la tienda de aplicaciones, debes inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android.

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

npx cap open ios
npx cap open android

Una vez que estén configurados tus proyectos nativos, desplegar tu aplicación en un dispositivo conectado es un proceso sencillo.

Para Android Studio, espera a que todo se cargue y luego despliega tu aplicación en un dispositivo conectado.

Para Xcode, establece tu cuenta de firma para desplegar tu aplicación en un dispositivo real en lugar del simulador. Una vez que hayas hecho eso, simplemente presiona play para ejecutar la aplicación en tu dispositivo conectado, que puedes elegir en la parte superior.

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

Capacitor Live Reload

Los frameworks de desarrollo modernos suelen venir con recarga caliente, y afortunadamente, puedes tener lo mismo con Capacitor pero en tu dispositivo móvil!

Puedes hacer que tu aplicación alojada localmente esté accesible con recarga en vivo en tu 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 para que cargue 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 usar la IP y el puerto precisos. Ejecuta npx cap copy para aplicar estos cambios a nuestro proyecto nativo.

Una vez que despliegues 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!

Ten en cuenta que si se instalan nuevos plugins, como la cámara, es necesario realizar una reconstrucción de 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 Capacitor plugin. Vamos a instalar uno simple, el Share plugin, que despliega el diálogo de compartir nativo:

npm i @capacitor/share

Para utilizarlo, importa el paquete y llama al método correspondiente desde nuestra aplicación. Considera el share() App.js Después de instalar un nuevo plugin, recuerda sincronizar tu proyecto de React nuevamente usando:

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;

A continuación, puedes hacer que la aplicación se sienta más nativa en iOS y Android con __CAPGO_KEEP_0__ navegación y transiciones, y solucionar problemas de diseño comunes en 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

protectedTokens Ionic para construir aplicaciones de múltiples plataformas, pero integrarlo con React es engorroso y raramente vale la pena cuando ya tienes Tailwind CSS.

Para un sentir móvil nativo en una aplicación React + Capacitor, utilice Capgo plugins en lugar de kits de interfaz de usuario web solo como Konsta UI:

• @capgo/capacitor-navegación-nativa — barra de navegación nativa, Liquid Glass barra de pestañas en iOS, y un estilo de barra de pestañas difuminado en Android. Su router de React mantiene el estado de ruta; el plugin es dueño de la barra de chrome nativa.
• @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso de arrastre en la capa de WebView en iOS, 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 propiedad del sistema; Android utiliza un fondo difuminado de la capa 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 la caja de su 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 páginas de rutas en cap-router-outlet, cap-page, y cap-content, y llame setDirection('forward') o setDirection('back') antes de navegar. No duplique encabezados o pie de página web cuando la navegación nativa posee 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). Ofrece safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor:

bun add -D tailwind-capacitor

In src/index.css:

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

Utilice utilidades como pt-safe, pb-safe, y px-safe en lugar de agregarlas env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para su configuración de React, abre una solicitud de extracción en GitHub.

Corrección de problemas de diseño de iOS (Vista de pantalla, Á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 vista previa sola no suele solucionar el problema. Pase por estas comprobaciones en orden.

Asegúrese de que la etiqueta meta de viewport se aplique correctamente

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

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

Administre el área segura de iOS desde un solo envoltorio raíz

Crear un solo concha de aplicación y aplique allí el relleno de área segura — 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);
}

Envuelva todo el contenido de la página dentro de .app-shellEl relleno de área segura duplicado en encabezados, modales y envoltorios de diseño a menudo hace que la interfaz de usuario se vea recortada o demasiado grande.

Con @capgo/tailwind-capacitor, puede expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola concha.

Establezca Capacitor iOS contentInset To never primero

En capacitor.config.ts, prefiera el área de inserción nativa deshabilitada y deja que CSS (o la navegación nativa) tenga el área de seguridad: contentInsetMode: 'css'Mezclar el área de inserción automática de __CAPGO_KEEP_0__ con CSS

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Encuentra el elemento que está desbordando realmente

El culpable usual es un elemento que utiliza

, Tailwind 100vw, una anchura de píxeles fija, o un tamaño w-screenEn Safari Web Inspector, ejecuta: 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 cuando sea posible. Muchos problemas de rebosamiento horizontal provienen de 100vw / w-screenduplicado relleno de área segura, o un contenedor de ancho fijo — no del etiqueta meta de viewport en sí misma.

Conclusión

Capacitor ofrece un medio fluido para construir aplicaciones nativas basadas en un proyecto web existente, proporcionando una forma simple 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 proyectos web de React.js. Lleva tus habilidades de 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 para una cuenta gratuita hoy.

Sigue adelante desde Construyendo Aplicaciones Móviles con React.js Puro y Capacitor

Si estás utilizando Desarrollar Aplicaciones Móviles con React.js Puro y Capacitor para planificar el comportamiento de medios y interfaces nativas, conectarlo 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-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos, @capgo/capacitor-reproductor-de-videos para el detalle de implementación en @capgo/capacitor-reproductor-de-videos, y Usando @capgo/capacitor-navegación-nativa para la capacidad nativa en Usando @capgo/capacitor-navegación-nativa.