Monorepo React Native 2026: pnpm + Turborepo + Expo SDK 55

Actualizado: 13 de agosto de 2026

Un monorepo React Native es un único repositorio que contiene la app móvil (iOS/Android), aplicaciones web y paquetes compartidos bajo un mismo grafo de dependencias, y, en 2026, la combinación que estoy usando en producción sin dolores de cabeza es pnpm workspaces + Turborepo + Expo SDK 55 + el soporte nativo de Metro para monorepos. En este tutorial paso a paso configuro la estructura, resuelvo la trampa de watchFolders en Metro, dejo listo EAS Build con pnpm y comparto componentes entre apps/mobile y apps/web sin duplicar React ni React Native.

• La pila estable en 2026 es pnpm 10 + Turborepo 2 + Expo SDK 55 + Metro con soporte de watchFolders nativo; funciona mejor con node-linker=hoisted porque React Native espera un node_modules plano.
• Metro requiere watchFolders apuntando a la raíz del workspace y nodeModulesPaths incluyendo tanto la app como la raíz; sin eso aparece el clásico "Unable to resolve module" incluso cuando el archivo existe.
• EAS Build no asume pnpm por defecto: fija la versión en packageManager del package.json, usa la bandera --workspace-root (nueva en SDK 55) y ajusta las rutas de build.gradle a la raíz del monorepo.
• Turborepo cachea tareas por hash de inputs y con Remote Caching comparte artefactos entre desarrolladores y CI; turbo run typecheck pasa de 45s a <2s en cache-hit.
• Los paquetes compartidos (packages/ui, packages/api, packages/types) deben declarar react y react-native como peerDependencies, nunca como dependencies, para evitar el error "Invalid hook call" por dobles copias de React.
• Auditar con pnpm why react y pnpm why react-native antes de cada release: exactamente una versión de cada uno, sin excepciones.

¿Qué es un monorepo en React Native y por qué usarlo?

Un monorepo es un repositorio único que aloja varias aplicaciones y paquetes con un solo grafo de dependencias, un solo lockfile y una sola cadena de build. En React Native, esto significa que la app iOS/Android en apps/mobile, el sitio Next.js en apps/web y los paquetes compartidos (packages/ui, packages/api, packages/types) viven bajo el mismo árbol y consumen las mismas versiones de dependencias críticas: react, react-native, TypeScript, ESLint, Zod.

En mi experiencia liderando equipos de plataforma en fintech, la razón real para adoptar monorepo no es "ahorrar repos" sino habilitar refactors atómicos: cambiar un contrato de API en packages/api y ver de inmediato qué apps rompen, todo en un único PR verificable por CI. Un polyrepo lo hace posible en teoría, pero en la práctica siempre acumulas versiones desfasadas y "olvidos" de sincronización.

La otra razón, más pragmática, es la tipación end-to-end. Con packages/types declarando los DTO del backend y compartidos por la app móvil y el web, un cambio de campo en el backend produce error de compilación en el cliente en cuestión de segundos. Sin monorepo, ese error aparece en producción.

La contrapartida son las tres batallas que este artículo resuelve: configuración de Metro, compatibilidad de EAS Build con pnpm y duplicación accidental de React o React Native. Si esos tres frentes están cerrados, un monorepo React Native es tan estable como cualquier configuración de app aislada.

Estructura de directorios recomendada

La estructura que uso en producción separa claramente aplicaciones (deployables) de paquetes (bibliotecas internas). Un único package.json en la raíz gestiona el workspace y el packageManager, y cada aplicación o paquete declara sus propias dependencias:

acme/
├── package.json                # raíz: workspaces + scripts turbo
├── pnpm-workspace.yaml         # define apps/* y packages/*
├── pnpm-lock.yaml              # ÚNICO lockfile
├── turbo.json                  # pipelines de Turborepo
├── .npmrc                      # node-linker=hoisted, public-hoist-pattern
├── tsconfig.base.json          # TS base compartido
├── apps/
│   ├── mobile/                 # Expo SDK 55 (React Native 0.83)
│   │   ├── app/                # rutas Expo Router
│   │   ├── metro.config.js
│   │   ├── package.json
│   │   └── eas.json
│   └── web/                    # Next.js 15 (opcional)
│       └── package.json
├── packages/
│   ├── ui/                     # componentes RN cross-platform
│   │   ├── src/
│   │   └── package.json
│   ├── api/                    # cliente tRPC/REST tipado
│   ├── types/                  # DTO + Zod schemas
│   ├── hooks/                  # hooks React reutilizables
│   └── config/                 # ESLint, Prettier, tsconfig presets
└── tooling/
    └── scripts/                # scripts de mantenimiento

Honestamente, son tres reglas que aplico sin excepción (aprendidas después de romper builds ajenos más de una vez). Primero, ningún paquete de packages/* depende de otra app de apps/*: la dirección de las dependencias siempre va de app a paquete, nunca al revés. Segundo, los paquetes exportan TypeScript sin transpilar y Metro los consume directamente vía transformer, lo que evita el paso de build intermedio y acelera el HMR. Tercero, cada paquete público expone sólo su src/index.ts en el main/module del package.json; los internos permanecen fuera del contrato.

Configurar pnpm workspaces paso a paso

Empieza activando Corepack para fijar la versión de pnpm en el repositorio y evitar drift entre máquinas. Con Node 22 LTS ya viene incluido:

corepack enable
corepack prepare [email protected] --activate

mkdir acme && cd acme
git init
pnpm init

Ahora crea pnpm-workspace.yaml en la raíz. Este archivo le dice a pnpm qué carpetas contienen sub-paquetes, y en 2026 también aloja la lista de paquetes con scripts de build permitidos (onlyBuiltDependencies), un cambio de seguridad importante que pnpm introdujo tras varios incidentes de supply chain:

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

onlyBuiltDependencies:
  - sharp
  - unrs-resolver
  - "@swc/core"
  - esbuild

El siguiente paso es el que evita más horas de debugging: crear un .npmrc en la raíz con node-linker=hoisted. Por defecto, pnpm usa un layout aislado con enlaces simbólicos que respeta las declaraciones exactas de dependencias. Es elegante en Node puro, pero React Native espera un node_modules plano como el de npm/yarn, y sin este cambio verás errores de codegen y compilación Kotlin muy difíciles de diagnosticar:

# .npmrc
node-linker=hoisted
strict-peer-dependencies=false
auto-install-peers=true
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*
public-hoist-pattern[]=@types/*

Finalmente, edita el package.json raíz. Fija packageManager para que EAS Build no adivine, marca el proyecto como private: true para evitar publicaciones accidentales, y añade los scripts que Turborepo orquestará:

{
  "name": "acme",
  "private": true,
  "packageManager": "[email protected]",
  "engines": { "node": ">=22" },
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "lint": "turbo lint",
    "typecheck": "turbo typecheck",
    "test": "turbo test",
    "clean": "turbo clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^2.5.0",
    "typescript": "~5.6.3",
    "prettier": "^3.4.2"
  }
}

Bootstrapping de la app Expo SDK 55

Con la raíz lista, crea la app móvil dentro de apps/mobile. Expo por defecto asume npm, así que hay que reinicializar dependencias con pnpm:

mkdir -p apps && cd apps
npx create-expo-app@latest mobile --template default
cd mobile
rm -rf node_modules package-lock.json
cd ../..
pnpm install

Ahora ajusta el apps/mobile/package.json para que consuma los paquetes locales por nombre, y pnpm resuelve workspace:* a la carpeta hermana automáticamente:

{
  "name": "@acme/mobile",
  "main": "expo-router/entry",
  "version": "1.0.0",
  "scripts": {
    "start": "expo start",
    "android": "expo run:android",
    "ios": "expo run:ios",
    "typecheck": "tsc --noEmit",
    "lint": "eslint ."
  },
  "dependencies": {
    "expo": "~55.0.0",
    "expo-router": "~5.0.0",
    "react": "19.1.0",
    "react-native": "0.83.0",
    "@acme/ui": "workspace:*",
    "@acme/api": "workspace:*",
    "@acme/types": "workspace:*"
  }
}

Sigue la guía oficial de monorepos de Expo como referencia canónica, especialmente para las rutas de assets en cada release del SDK. Si vas a compartir estilos entre apps con Tailwind, mi artículo sobre NativeWind v4 en React Native explica cómo colocar el tailwind.config.js a nivel de packages/ui para que ambas apps hereden el mismo sistema de design tokens.

Cómo configurar Metro para un monorepo

Aquí es donde el 80% de los equipos se atascan. Metro, el bundler de React Native, resuelve módulos relativos al paquete que los importa. En un monorepo, eso hace que Metro no encuentre nada fuera de apps/mobile/node_modules. La solución tiene tres piezas: watchFolders apuntando a la raíz, nodeModulesPaths con ambas rutas, y (opcional pero recomendado) disableHierarchicalLookup: true para evitar sorpresas de escaneo.

// apps/mobile/metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const path = require('node:path');

const projectRoot = __dirname;
const monorepoRoot = path.resolve(projectRoot, '../..');

const config = getDefaultConfig(projectRoot);

// 1) Metro debe vigilar toda la raíz del monorepo
config.watchFolders = [monorepoRoot];

// 2) Y buscar módulos primero en la app, luego en la raíz
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(monorepoRoot, 'node_modules'),
];

// 3) Desactiva la búsqueda jerárquica: previene resoluciones duplicadas
config.resolver.disableHierarchicalLookup = true;

module.exports = config;

Para cargas más grandes, añade un .watchmanconfig en la raíz que excluya artefactos de build. Sin esto, Metro puede intentar vigilar ios/build o android/build y consumir memoria en cantidades absurdas:

{
  "ignore_dirs": [".git", "node_modules/.cache", "**/ios/build", "**/android/build", "**/.turbo", "**/dist"]
}

La documentación oficial de Metro también documenta resolver.extraNodeModules para casos donde necesitas apuntar un nombre lógico a una ruta específica; en la práctica raras veces lo necesito con pnpm en modo hoisted.

Turborepo: pipelines, tareas y caché remoto

Turborepo 2 transforma la orquestación del monorepo en un grafo de dependencias declarativo. En turbo.json, cada tarea define sus inputs, sus outputs y qué otras tareas deben completarse antes. Con eso, Turbo calcula un hash por tarea, cachea resultados y en un segundo turbo run typecheck devuelve todo desde caché si nada cambió:

{
  "$schema": "https://turborepo.com/schema.json",
  "globalDependencies": ["tsconfig.base.json", ".env.example"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".expo/**"],
      "cache": true
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json", "tsconfig.base.json"],
      "outputs": []
    },
    "lint": {
      "inputs": ["src/**", ".eslintrc*", "eslint.config.*"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "__tests__/**", "vitest.config.*"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

El símbolo ^ en dependsOn significa "esperar a que la tarea correspondiente termine en todos los paquetes de los que dependo". Es decir, @acme/mobile no arranca su build hasta que @acme/ui y @acme/api hayan terminado el suyo. Sin esa relación, Turbo paraleliza a ciegas y produce resultados no reproducibles.

Para caché compartida entre CI y desarrolladores, conecta Vercel Remote Cache con npx turbo login && npx turbo link. En equipos de 6+ personas, en promedio esto recorta 40-60% del tiempo de CI porque los typechecks y linters se sirven desde caché sin volver a ejecutarse. Si tu equipo aún ejecuta las suites de pruebas en cada PR, revisa mi guía de testing y depuración en React Native — Jest 30 se integra bien con la caché de Turbo si aíslas correctamente los inputs de cada paquete.

Paquetes compartidos: UI, tipos y clientes de API

Los paquetes son donde el monorepo realmente paga. Un packages/ui típico exporta componentes cross-platform escritos en TypeScript. La clave es declarar react y react-native como peerDependencies, nunca como dependencies:

{
  "name": "@acme/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "sideEffects": false,
  "peerDependencies": {
    "react": "^19.0.0",
    "react-native": ">=0.80.0"
  },
  "devDependencies": {
    "react": "19.1.0",
    "react-native": "0.83.0",
    "typescript": "~5.6.3"
  }
}

Un componente Button tipado que consume tokens de tema del propio paquete:

// packages/ui/src/Button.tsx
import { Pressable, Text, StyleSheet, type PressableProps } from 'react-native';
import { tokens } from './tokens';

export type ButtonVariant = 'primary' | 'secondary' | 'ghost';

export interface ButtonProps extends PressableProps {
  label: string;
  variant?: ButtonVariant;
}

export function Button({ label, variant = 'primary', ...rest }: ButtonProps) {
  return (
    <Pressable
      accessibilityRole="button"
      style={({ pressed }) => [
        styles.base,
        styles[variant],
        pressed && { opacity: 0.85 },
      ]}
      {...rest}
    >
      <Text style={[styles.label, styles[`${variant}Label`]]}>{label}</Text>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  base: {
    paddingVertical: 12,
    paddingHorizontal: 20,
    borderRadius: 10,
    alignItems: 'center',
  },
  primary: { backgroundColor: tokens.color.brand },
  secondary: { backgroundColor: tokens.color.surface },
  ghost: { backgroundColor: 'transparent' },
  label: { fontSize: 16, fontWeight: '600' },
  primaryLabel: { color: tokens.color.onBrand },
  secondaryLabel: { color: tokens.color.onSurface },
  ghostLabel: { color: tokens.color.brand },
});

Para los tipos y validación, un packages/types con esquemas Zod es el patrón que uso en fintech: los mismos esquemas validan input en la app móvil, tipan el cliente de API y sirven como source-of-truth compartido con el backend. Cubro este patrón con más detalle en la guía de formularios con React Hook Form y Zod, y encaja perfectamente en un monorepo porque el mismo esquema se importa desde @acme/types tanto en apps/mobile como en apps/web.

EAS Build con pnpm en un monorepo

El build en la nube de Expo tuvo históricamente asunciones de Yarn cableadas. Desde principios de 2026, con la EAS CLI 16+ y Expo SDK 55, pnpm está soportado de primera clase, pero sigue habiendo tres frentes que hay que blindar en cada configuración.

1) Fijar la versión de pnpm. El campo packageManager en el package.json raíz es la única fuente de verdad; EAS lo lee y usa exactamente esa versión en el worker remoto. Sin él, los builds de Android suelen romper con "corepack: unknown pnpm version" o instalan una versión distinta a la local.

2) Habilitar el modo workspace. En apps/mobile/eas.json, declara que el build debe operar desde la raíz del monorepo:

{
  "cli": { "version": ">= 16.0.0", "appVersionSource": "remote" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "channel": "development",
      "env": { "EXPO_NO_TELEMETRY": "1" }
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "cache": { "disabled": false, "key": "acme-preview" }
    },
    "production": {
      "channel": "production",
      "autoIncrement": true
    }
  },
  "submit": { "production": {} }
}

Ejecuta el build desde la raíz con la bandera nueva:

pnpm exec eas build --platform ios --profile production --workspace-root

3) Ajustar rutas nativas para Android. Cuando corras expo prebuild, el archivo apps/mobile/android/app/build.gradle apuntará a ../node_modules/react-native por defecto. En un monorepo hoisted, React Native vive en la raíz. Corrige las rutas:

// apps/mobile/android/app/build.gradle
react {
    reactNativeDir = file("../../../../node_modules/react-native")
    codegenDir     = file("../../../../node_modules/@react-native/codegen")
    cliFile        = file("../../../../node_modules/react-native/cli.js")
    autolinkLibrariesWithApp()
}

Para el pipeline completo de despliegue, incluidas EAS Submit y EAS Update sobre esta base, sigue el playbook detallado en el despliegue de apps React Native con EAS.

Cómo solucionar "Unable to resolve module" y otros errores comunes

Estos son los ocho errores que veo aparecer una y otra vez cuando reviso monorepos ajenos. La buena noticia: casi todos se resuelven en menos de cinco minutos si sabes dónde mirar.

Síntoma	Causa raíz	Solución
"Unable to resolve module @acme/ui"	Metro no vigila la raíz del monorepo	Añade monorepoRoot a watchFolders y a nodeModulesPaths
"Invalid hook call" en runtime	Dos copias de React resueltas por pnpm	Declarar react como peerDependency; auditar con pnpm why react
"Duplicate module: react-native"	Dos versiones de RN en el árbol	Añadir resolutions/overrides en la raíz para pin exacto
"Cannot find module @react-native/codegen"	Rutas de build.gradle mal ajustadas	Recuenta niveles de ../ hasta la raíz
Codegen crash en Kotlin	pnpm en modo isolated con symlinks	Cambiar a node-linker=hoisted en .npmrc
EAS falla con "unknown pnpm version"	Falta packageManager en package.json	Añadir "packageManager": "[email protected]"
Peer dep faltante (react-native-gesture-handler)	pnpm no auto-instala transitivas	pnpm exec expo install react-native-gesture-handler
Metro consume 8GB de RAM	watchFolders escanea ios/build	Añadir un .watchmanconfig con ignore_dirs

Cuando ninguna de estas soluciones sirve, el 90% de las veces el problema es una versión duplicada de React Native oculta en el árbol. Este script me ha desbloqueado antes de más de un release nocturno:

pnpm why react-native
pnpm why react
pnpm why @react-native/codegen
find node_modules -name "react-native" -type d -maxdepth 4

Si aparece más de una ocurrencia real (no simbólica), fija la versión con pnpm.overrides en la raíz del package.json:

{
  "pnpm": {
    "overrides": {
      "react": "19.1.0",
      "react-native": "0.83.0",
      "@react-native/codegen": "0.83.0"
    }
  }
}

Compartir código con Next.js y React Native

El caso avanzado, y el motivo por el que muchos equipos adoptan monorepo, es publicar la misma pantalla en móvil y web. La receta comprobada en 2026 combina Expo Router en apps/mobile, Next.js 15 con App Router en apps/web y un packages/ui que exporta primitivas React Native puras. En Next.js, esas primitivas se resuelven mediante react-native-web, que mapea View, Text y StyleSheet a DOM real.

// apps/web/next.config.mjs
import { withExpo } from '@expo/next-adapter';

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  transpilePackages: [
    'react-native',
    'react-native-web',
    'expo',
    '@acme/ui',
    '@acme/api',
    '@acme/types',
  ],
  experimental: {
    forceSwcTransforms: true,
  },
};

export default withExpo(nextConfig);

La condición para que esto funcione es doble: los paquetes compartidos exportan TypeScript sin transpilar, y transpilePackages incluye a todos ellos. Sin esa lista, Next.js no procesa los archivos .tsx de los paquetes y devuelve errores de parse en producción.

Para navegación, la abstracción común la maneja Solito, que unifica expo-router y next/navigation tras una API común. Es opcional — si tu packages/ui se mantiene puramente presentacional y la navegación vive dentro de cada app, no necesitas Solito. Complementa esto con la guía de navegación con Expo Router y React Navigation 7 para elegir estrategia según la complejidad de tu producto.

Preguntas frecuentes

¿Vale la pena usar un monorepo para un solo equipo pequeño?

Sí si prevés más de una app o un paquete compartido (por ejemplo, tipos con el backend). Para una sola app aislada sin dependencias internas, un monorepo añade complejidad de configuración sin beneficio real. La regla que aplico: dos "cosas deployables" o una app + un paquete compartido justifican el monorepo.

¿Por qué elegir pnpm en lugar de Yarn o npm workspaces?

pnpm resuelve dependencias de forma más estricta y con mejor rendimiento en instalaciones frescas (30-50% más rápido que Yarn Classic en mi benchmark interno). Además, pnpm.overrides es más fiable que resolutions de Yarn, y el modo hoisted imita el comportamiento que React Native espera sin la fragilidad de los symlinks aislados.

¿EAS Build soporta pnpm oficialmente en 2026?

Sí. Desde EAS CLI 16 y Expo SDK 55, pnpm está soportado si fijas packageManager en el package.json, usas la bandera --workspace-root y ajustas las rutas de build.gradle a la raíz. Sin esos tres pasos, EAS puede fallar con errores de codegen o de resolución de módulos en Android.

¿Qué diferencia hay entre node-linker=hoisted e isolated?

El modo isolated (por defecto en pnpm) crea un node_modules con symlinks al store global, respetando declaraciones estrictas. El modo hoisted genera un node_modules plano como el de npm. React Native espera hoisted porque su build de Android y su codegen no siguen symlinks correctamente.

¿Puedo usar Nx en lugar de Turborepo con React Native?

Sí, Nx es una alternativa madura con integración de primera clase para React Native vía @nx/expo y @nx/react-native. La elección entre Turborepo y Nx depende del equipo: Turborepo es más ligero y opinado, Nx ofrece más generadores y automatización pero con curva de aprendizaje mayor. Para equipos que arrancan monorepo, Turborepo suele ser el punto de entrada más rápido.