How to Create a Monorepo for Web and Mobile App Development

Overview

A monorepo is a single repository that contains multiple apps and packages. In a cross-platform setup, that usually means a web app, a mobile app, shared libraries, and infrastructure or backend code living together. The main benefit is coordination: shared code is versioned in the same place as the apps that use it, and changes can be tested together.

For teams trying to build web apps faster while also maintaining a mobile client, this can be a strong fit. You can centralize developer productivity tools, standardize CI/CD for app development, and reduce the overhead of publishing and consuming internal packages across multiple repositories.

Still, a monorepo is not automatically simpler. It works best when you have real shared surface area, such as:

• TypeScript types shared between frontend and backend
• API clients and validation schemas used by web and mobile apps
• Shared UI tokens, design primitives, or business logic
• Common linting, testing, and formatting rules
• Unified deployment and preview workflows

It works less well when your apps are largely unrelated, owned by separate teams with different release cadences, or built on stacks that have little overlap.

A practical default for many teams is this: keep the apps separate at the runtime layer, but share what is truly portable. That usually means types, utilities, API contracts, validation, and design tokens. Be more cautious with shared UI. Web and mobile UI often diverge faster than teams expect.

For mobile, especially with React Native, the safest evergreen guidance is to start with a framework rather than hand-assembling the foundation yourself. The current React Native guidance recommends using a framework for new apps because common concerns such as navigation, native dependencies, and access to native APIs are already solved more coherently. That advice matters in a monorepo too. A mobile app that already depends on a well-supported framework is usually easier to integrate into a stable repository structure than a highly custom setup.

Step-by-step workflow

Use this workflow to create a monorepo for web and mobile apps without turning the repository into a dumping ground.

1. Decide what should be shared

Before you choose tools, list the assets that genuinely belong in one place. This step prevents the most common monorepo mistake: combining projects first and inventing a rationale later.

A good candidate list looks like this:

• packages/types for shared domain models and API response types
• packages/api-client for authenticated requests, retry logic, and endpoint wrappers
• packages/config for ESLint, TypeScript, Prettier, and shared build settings
• packages/utils for pure functions with no platform-specific dependencies
• packages/ui-tokens for colors, spacing, typography scales, and theme constants

What usually should not be shared early on:

• Large presentation-layer component libraries across web and native unless your team has clear conventions
• Platform-specific modules that require frequent conditional logic
• Everything in the name of consistency

If you cannot identify at least two or three stable shared packages, a monorepo may not be worth it yet.

2. Pick a repo layout with explicit boundaries

A conventional layout is a good starting point:

apps/
  web/
  mobile/
  api/
packages/
  types/
  api-client/
  utils/
  ui-tokens/
  config/
tooling/
  scripts/
  ci/

This structure keeps deployable applications under apps and reusable code under packages. That distinction matters. It tells contributors which projects ship independently and which modules support multiple apps.

If you run backend services alongside your clients, keeping the API in the same monorepo can simplify cloud app development and app integrations. Shared validation schemas and request types become easier to maintain. If your backend has separate compliance or infrastructure constraints, you may still prefer an external repository.

3. Choose a workspace manager and task runner

For JavaScript and TypeScript teams, package manager workspaces are the foundation. Pair them with a task orchestrator such as Turborepo if you want cached builds, dependency-aware task execution, and a smoother local developer experience. That is why many teams researching “Turborepo mobile web” start there: the value is less about novelty and more about making builds and tests scale as the repository grows.

Your baseline setup should support:

• Workspace-level dependency installation
• Local linking between apps and packages
• Task pipelines for build, lint, test, typecheck, and dev
• Caching to avoid rerunning unaffected work

Do not over-optimize in week one. A clear workspace layout with reliable scripts is more important than a highly customized pipeline.

4. Start each app with the right framework

The web app can use the framework that fits your hosting and rendering needs. The mobile app should start with a framework-supported React Native setup unless you have unusual platform constraints. Current React Native guidance is clear that most new apps benefit from a framework because it solves common needs such as navigation, native dependency management, and core app scaffolding. In practice, this reduces maintenance burden inside the monorepo because fewer foundational decisions are left to ad hoc library choices.

The principle here is simple: share code where it helps, but let each app keep a framework that suits its runtime.

5. Build shared packages around contracts, not convenience

The most durable shared code is contract-oriented. Think schemas, types, auth helpers, API wrappers, and business rules. These packages change more slowly and create real leverage.

For example:

• A shared auth package can manage token parsing, session shape, and request headers while web and mobile implement their own storage details.
• A shared API client can define endpoints and validation while platform apps control retries, caching, and offline behavior at the edge.
• A shared design token package can expose colors and spacing while each app renders components in its own way.

This is a better long-term pattern than forcing one UI abstraction layer across every screen and component.

6. Standardize local development

A monorepo should make development more predictable, not more magical. Add root scripts that developers can remember:

• dev:web
• dev:mobile
• dev:api
• lint
• test
• typecheck

Document environment variables carefully. Shared packages should not quietly depend on app-specific secrets. Keep app env files scoped to each application and expose only what shared modules truly need.

This is also where developer utilities help. Consistent scripts, code generation, schema validation, and formatting reduce friction far more than clever folder names.

7. Set up CI by affected project, not whole-repo habit

One of the biggest monorepo wins is targeted CI/CD for app development. If a change only affects apps/web and packages/types, your pipeline should not rebuild every mobile artifact by default.

A practical CI flow looks like this:

1. Install dependencies once
2. Detect changed files and affected packages
3. Run lint, typecheck, and tests for affected workspaces
4. Build only the impacted apps
5. Deploy preview environments for the web app when appropriate
6. Trigger mobile build or release jobs only when mobile-related paths change

This keeps deployment complexity manageable while preserving the benefit of a unified repository. If you want a deeper deployment pattern, see How to Set Up Preview Deployments for Every Pull Request and CI/CD Pipeline for React Native Apps: A Step-by-Step Guide.

8. Define ownership and review paths

Monorepos fail socially before they fail technically. Add ownership rules so changes to shared packages require the right reviewers. A web feature team should not unknowingly break mobile login because shared auth helpers changed without mobile review.

Even a lightweight ownership map helps:

• Web team owns apps/web
• Mobile team owns apps/mobile
• Platform or senior maintainers co-own packages/types, packages/config, and CI scripts

That keeps handoffs clear and lowers the risk of accidental platform drift.

Tools and handoffs

A good monorepo is not just a folder structure. It is a set of deliberate handoffs between teams, tools, and deployment targets.

Core tool categories

• Workspace management: use package manager workspaces to install and link dependencies consistently.
• Task orchestration: use a tool like Turborepo when the repo grows enough to justify caching and affected-task execution.
• Type safety and contracts: TypeScript, schema validation, and generated API clients help web and mobile stay aligned.
• CI platform: your CI system should support path filters, matrix jobs, caches, and environment-specific secrets.
• Hosting and deployment: keep web deployment, backend deployment, and mobile release workflows separate even if they start from one repository.

Typical handoffs in a cross-platform monorepo

Design to engineering: move shared design tokens into a package, not fully shared components by default. This gives both platforms a common visual language without forcing one rendering model.

Backend to client apps: publish API changes through schemas and generated types. This is one of the highest-value forms of shared code web and mobile teams can maintain together.

Platform to feature teams: centralize linting, formatting, and CI templates in shared config packages so feature teams do not rebuild the same tooling repeatedly.

Release management: tag and version apps independently if needed, even inside one repository. A monorepo does not require synchronized releases.

If you are still choosing adjacent parts of the stack, these guides can help round out the architecture: How to Choose a Web App Tech Stack: Frontend, Backend, Database, and Hosting, Mobile App Backend Options Compared: Firebase, Supabase, and Custom APIs, and Best Authentication Providers for Web and Mobile Apps.

Quality checks

Once the monorepo is running, quality comes from guardrails more than from structure alone. Use this checklist to keep the setup healthy.

Monorepo quality checklist

• Shared packages are platform-agnostic by default. If a package starts importing web-only or native-only APIs, split it.
• Every app can build independently. The web app should not require mobile tooling to compile, and vice versa.
• Type boundaries are explicit. Shared types should be versioned through repository changes, not copied manually.
• CI jobs are path-aware. A docs change should not trigger every heavy workflow.
• Ownership is documented. Shared packages need named maintainers.
• Local setup is reproducible. A new developer should be able to install, run, and test the affected app without tribal knowledge.
• Deployments stay separate. One repo does not mean one release train.

Common failure modes

Too much shared UI: teams often start by sharing components across web and mobile and end up with abstractions that satisfy neither platform well.

Slow CI: if every pull request runs all builds, the monorepo becomes a bottleneck instead of a productivity gain.

Confused package boundaries: utility packages slowly absorb platform code, creating hidden dependencies and brittle builds.

Unclear deployment ownership: when web, API, and mobile releases are mixed in one pipeline, debugging becomes harder.

To keep production readiness in view, pair your monorepo process with environment-specific deployment guidance such as Web App Deployment Checklist for Production Releases and hosting comparisons like App Hosting Comparison: Vercel vs Netlify vs Cloudflare vs AWS.

When to revisit

A monorepo is not a one-time architecture decision. Revisit it when the inputs change, especially the frameworks, release process, or amount of shared code.

Set a recurring review around these triggers:

• You add a new app such as an admin dashboard or a second mobile client
• Your framework changes on web or React Native, affecting build assumptions
• CI times start growing enough to slow pull requests
• Shared packages multiply and boundaries become fuzzy
• Your deployment model changes due to hosting, compliance, or scaling needs
• Teams reorganize and ownership lines need to be updated

A useful quarterly review asks five practical questions:

1. Which shared packages saved real work this quarter?
2. Which packages created coupling without enough payoff?
3. Are web and mobile still benefiting from common contracts?
4. Is CI/CD helping selective delivery, or has it become whole-repo automation?
5. What should be split, simplified, or documented better?

If you are building a monorepo for the first time, start modestly. Put the web app, mobile app, shared types, API client, and config in one repository. Make affected CI work. Keep deployments independent. Then expand only where the shared code has proved its value.

That approach is usually what makes monorepo app development sustainable: not maximum consolidation, but clear boundaries, useful shared contracts, and workflows that respect the differences between web and mobile platforms.

Your next practical steps are straightforward:

1. Create the apps/ and packages/ structure.
2. Move shared types and config first.
3. Adopt a framework-based React Native setup for the mobile app unless you have unusual constraints.
4. Add path-aware CI for lint, test, typecheck, and build.
5. Review after the first two releases and remove any shared package that is creating more friction than leverage.

That gives you a monorepo that can help teams build web apps faster, support mobile app development tools more cleanly, and evolve with your stack instead of locking you into it.