React Native Monorepo Setup with Turborepo

Key facts, with sources

• React Native 0.76, released October 23, 2024, enabled the New Architecture by default and shipped with over 1,070 commits from 156 contributors plus a roughly 15x faster Metro resolver. (React Native official blog)
• The State of React Native 2024 survey collected 3,501 responses, up from about 2,400 the previous year, covering more than 15 areas of the ecosystem. (State of React Native survey)
• About 20% of State of React Native 2024 respondents reported apps with more than 100,000 users, up from 14% the year before. (InfoQ)
• Shopify migrated all of its mobile apps to React Native over five years and reports sub-500ms (P75) screen loads and over 99.9% crash-free sessions in production. (Shopify Engineering)
• 88% of surveyed React Native developers feel the framework is progressing positively, while better debugging remains the top request, cited by 54% of respondents. (SSOJet (State of React Native 2024 highlights))

When a monorepo actually pays off

The monorepo earns its complexity when you have genuinely shared code and one team touching all of it: a mobile app and web dashboard hitting the same API, a design system expressed on both platforms, validation and business logic that must never drift between clients. In that world, a backend field rename becomes a single PR that updates the schema package and every consumer, checked by one CI run — versus two repos, two PRs, and a window where they disagree.

It does not pay off for a mobile-only product with no web sibling, or for separate teams that want independent release cadences and ownership boundaries — there, repo separation is the feature. My rule of thumb: if you are about to copy a types file or an API client between two repositories for the second time, stop and set up the monorepo instead.

Workspace layout that stays sane

The layout I use: an apps directory containing mobile (the React Native or Expo app) and web (Next.js), and a packages directory containing ui (shared design tokens and primitives), api-client (fetch layer plus zod schemas plus inferred types), core (domain logic and utilities), and config (shared eslint, TypeScript, and jest presets). Each package has its own package.json with an explicit name that apps import by — no reaching into sibling directories with relative paths.

Two conventions prevent later pain. First, shared packages export plain TypeScript compiled by each consumer's bundler — Metro and Next both handle transpiling workspace source directly, which avoids a build-watch dance during development. Second, anything platform-specific stays out of shared packages or behind platform-suffixed files; the moment packages/core imports react-native, your web build breaks and the boundary was fiction.

Configuring the Turborepo task graph

Turborepo's job is running tasks across the workspace in dependency order and caching everything deterministic. The configuration lives in turbo.json: build depends on the builds of upstream packages, typecheck and test depend on whatever they consume, and lint runs everywhere independently. Once configured, turbo run typecheck at the repo root checks the entire product, and — the part that transforms CI — caches results so packages untouched by a PR are skipped entirely.

With remote caching enabled, your CI and teammates share that cache, so a PR touching only the web app never re-runs mobile checks. In practice this turns monorepo CI from the thing everyone fears into the fastest CI most teams have had.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "typecheck": {
      "dependsOn": ["^build"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    }
  }
}

Making Metro understand the workspace

Metro is the step where most React Native monorepo attempts stall, because Metro by default watches only the app's own directory and resolves modules from its own node_modules. In a workspace, shared packages live outside the app folder and dependencies may be hoisted to the root node_modules, so an unconfigured Metro simply cannot find them.

The fix is three settings: watch the workspace root so edits to shared packages trigger reloads, add both the app's and the root's node_modules to the resolver paths, and — with Expo — start from expo/metro-config which handles much of this in recent SDKs. After changing Metro config, restart with a cleared cache; stale Metro caches cause more phantom monorepo bugs than any other single source.

const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');

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

const config = getDefaultConfig(projectRoot);

// Watch shared packages so edits hot-reload the app
config.watchFolders = [workspaceRoot];

// Resolve modules from the app first, then the hoisted root
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(workspaceRoot, 'node_modules'),
];

module.exports = config;

The pitfalls: duplicate React, hoisting, native modules

Three traps account for most monorepo misery. First, duplicate React: if the resolver finds two copies of react or react-native — one hoisted, one nested — you get the infamous invalid hook call errors that look like your bug but are not. Enforce a single version across every workspace package, and pin resolutions if a stray dependency drags in another copy. Second, hoisting surprises: some native libraries assume they live in the app's own node_modules; pnpm's stricter linking or targeted no-hoist rules tame this.

Third — the rule I state in every setup — native dependencies belong in the app package's own package.json, never only in a shared package. Autolinking scans the app's dependencies to generate the native build; a camera library declared only in packages/ui will typecheck perfectly and then fail at runtime with a missing native module. Shared packages may depend on native libraries as peer dependencies, but the app declares the real one.

CI and release flow for the workspace

The monorepo's CI story is where the setup pays rent daily. Every PR runs turbo run lint typecheck test at the root; Turborepo's cache and affected-package detection mean a docs change finishes in seconds while a shared-package change correctly fans out to every consumer. Mobile builds stay separate from PR checks — EAS Build or your native pipeline triggers on merges or tags, building from apps/mobile with the workspace intact, which EAS supports well.

Versioning stays simple if you let it: internal packages do not need semver ceremonies or publishing — apps consume workspace source directly, and the repo's git history is the version. Reserve real versioning for packages you publish externally. The one discipline to keep forever: shared-package PRs must run consumers' checks, never just their own — the entire point of the monorepo is that the api-client package cannot 'pass' while breaking the app importing it.

When to hire senior help

Bring in senior React Native help when facing a New Architecture or major version migration, persistent performance regressions, or a first store launch, since these are the phases where inexperienced teams lose the most months. A short senior architecture audit early in the project is consistently cheaper than a rescue or rewrite later. If your stack includes React Native + Python + AI, a senior engineer who owns the full product beats coordinating multiple juniors.

Bottom line

Dhairya Senjaliya ships Mobile — React Native Development projects worldwide — book a scoping call to discuss your specific situation.

Common pitfalls to avoid

• ✕Staying multiple versions behind on React Native, then facing a compound upgrade to the New Architecture because popular libraries have dropped old-architecture support
• ✕Treating React Native as write-once-run-anywhere and only QA-testing on iOS, shipping Android builds with broken back-button handling, keyboard behavior, and gesture bugs
• ✕Pulling in unmaintained third-party native modules without checking TurboModule and Fabric compatibility, which later blocks the New Architecture migration
• ✕Launching without crash and performance monitoring wired in, so the team only discovers jank and crash clusters from one-star reviews instead of telemetry

Frequently asked questions

Sources

• React Native official blog
• State of React Native survey
• InfoQ
• Shopify Engineering
• SSOJet (State of React Native 2024 highlights)