React Monorepo from Scratch: Next.js, Expo & NativeWind

Tue, 09 Sep 2025 00:00:00 +0000

By the end of this guide, you’ll have a working monorepo where a single set of React components renders on web, iOS, and Android:

We’ll use Next.js and Expo for the apps, NativeWind for cross-platform styling, and Turborepo for builds and caching. The template also includes a Vite + TanStack Router web app as a lighter alternative to Next.js. Familiarity with React, Next.js basics, and the terminal is assumed.

Rather just clone and go? Grab the universal-react-monorepo template.

Prerequisites

Node.js 18+, pnpm 10+
For mobile: iOS Simulator (macOS only) and/or Android Studio
Optional: Turbo CLI, GitHub CLI

Initialise the repository

Create a new project and set up git:

1mkdir mammoth && cd mammoth
2git init
3echo "# mammoth" > README.md
4git add README.md && git commit -m "Initial commit"

If you use GitHub CLI:

1gh repo create mammoth --public --source=. --remote=origin --push

Initialise the workspace with pnpm:

1pnpm init

Define the workspace

Create pnpm-workspace.yaml to tell pnpm which folders contain apps and packages:

1packages:
2 - "apps/*"
3 - "packages/*"

Create the folders:

1mkdir -p apps packages

Add a .gitignore:

1node_modules

Add Turborepo

Install Turborepo as a dev dependency:

1# terminal (repo root)
2pnpm add turbo --save-dev --workspace-root

Create turbo.json at the root:

 1// turbo.json (repo root)
 2{
 3 "$schema": "https://turborepo.com/schema.json",
 4 "ui": "tui",
 5 "tasks": {
 6 "build": {
 7 "dependsOn": ["^build"],
 8 "inputs": ["$TURBO_DEFAULTS$", ".env*"],
 9 "outputs": [".next/**", "!.next/cache/**", "dist/**"]
10 },
11 "typecheck": {
12 "dependsOn": ["^typecheck"]
13 },
14 "lint": {
15 "dependsOn": ["^lint"]
16 },
17 "dev": {
18 "persistent": true,
19 "cache": false
20 }
21 }
22}

Every script in an app or package that should run across the monorepo must be declared here. The tui view splits logs per task, which becomes useful once multiple apps are running.

Update .gitignore:

1node_modules
2.turbo

For a deeper understanding, read through the Turborepo documentation. There’s also an excellent walkthrough by Michael Guay covering Turborepo with pnpm workspaces.

Add the Next.js app

Create the web app inside apps/:

1# terminal (repo root)
2cd apps
3npx create-next-app@latest web --use-pnpm

Select the following options:

Wire scripts to Turborepo

Add root scripts so Turborepo orchestrates tasks across all apps and packages:

1// package.json (repo root)
2{
3 "scripts": {
4 "dev": "turbo dev",
5 "build": "turbo build",
6 "lint": "turbo lint",
7 "typecheck": "turbo typecheck"
8 }
9}

Update the web app scripts. The --webpack flag is needed because react-native-web isn’t compatible with Turbopack:

 1// package.json (apps/web)
 2{
 3 "scripts": {
 4 "dev": "next dev --webpack",
 5 "build": "next build --webpack",
 6 "start": "next start --webpack",
 7 "lint": "eslint",
 8 "typecheck": "tsc --noEmit"
 9 }
10}

Run pnpm install after editing scripts or dependencies to sync the lockfile.

Native builds approval

You might encounter this approve-builds warning:

This is pnpm’s safeguard for building native binaries. Run:

1# terminal (repo root)
2pnpm approve-builds

This records approved packages in pnpm-workspace.yaml:

1# pnpm-workspace.yaml (repo root)
2packages:
3 - apps/*
4 - packages/*
5
6onlyBuiltDependencies:
7 - sharp
8 - unrs-resolver

First build and caching

Run a full build:

1# terminal (repo root)
2turbo build

The first run is a cache miss:

Run it again:

1# terminal (repo root)
2turbo build

Cache hit:

The cached build replays in 83ms:

Turborepo hashes inputs and replays outputs on cache hits. You can enable Remote Caching to share artifacts across machines.

Add the Expo app

Inside apps/, create the mobile app:

1# terminal (repo root)
2cd apps
3npx create-expo-app@latest mobile

Expo defaults to npm. Switch to pnpm:

1# terminal (apps/mobile)
2cd mobile
3rm package-lock.json
4pnpm install

Reset the project configuration:

1# terminal (apps/mobile)
2pnpm run reset-project

Update package.json:

 1// package.json (apps/mobile)
 2{
 3 "scripts": {
 4 "dev": "expo start",
 5 "android": "expo start --android",
 6 "ios": "expo start --ios",
 7 "web": "expo start --web",
 8 "lint": "expo lint",
 9 "typecheck": "tsc --noEmit"
10 }
11}

Run pnpm install, then turbo dev from the repo root to start both apps.

Turborepo TUI

With two apps running, logs from web and mobile overlap:

The TUI (enabled in turbo.json) separates logs by task. Mobile logs:

Press the down arrow to switch to web:

Install NativeWind in Expo

NativeWind enables Tailwind CSS styling in React Native. Follow the official installation guide for the most up-to-date instructions.

Install the required packages:

1# terminal (apps/mobile)
2pnpm install nativewind react-native-reanimated@~4.1.2 react-native-safe-area-context@5.6.1
3pnpm install -D tailwindcss@^3.4.18 prettier-plugin-tailwindcss@^0.5.14

Initialise Tailwind:

1# terminal (apps/mobile)
2pnpm tailwindcss init

Configure Tailwind:

 1// tailwind.config.js (apps/mobile)
 2/** @type {import('tailwindcss').Config} */
 3module.exports = {
 4 content: [["./src/**/*.{js,jsx,ts,tsx}"]],
 5 presets: [require("nativewind/preset")],
 6 theme: {
 7 extend: {},
 8 },
 9 plugins: [],
10}

Create global styles:

1/* global.css (apps/mobile) */
2@tailwind base;
3@tailwind components;
4@tailwind utilities;

Configure Babel:

 1// babel.config.js (apps/mobile)
 2module.exports = function (api) {
 3 api.cache(true);
 4 return {
 5 presets: [
 6 ["babel-preset-expo", { jsxImportSource: "nativewind" }],
 7 "nativewind/babel",
 8 ],
 9 };
10};

Configure Metro:

1// metro.config.js (apps/mobile)
2const { getDefaultConfig } = require("expo/metro-config");
3const { withNativeWind } = require('nativewind/metro');
4
5const config = getDefaultConfig(__dirname)
6
7module.exports = withNativeWind(config, { input: './global.css' })

Add type support:

1// nativewind-env.d.ts (apps/mobile)
2/// <reference types="nativewind/types" />

Include it in tsconfig.json:

 1// tsconfig.json (apps/mobile)
 2{
 3 "include": [
 4 "**/*.ts",
 5 "**/*.tsx",
 6 ".expo/types/**/*.ts",
 7 "expo-env.d.ts",
 8 "nativewind-env.d.ts"
 9 ]
10}

Import the global CSS in your root layout:

1// _layout.tsx (apps/mobile/src/app)
2import { Stack } from "expo-router";
3import "../../global.css";
4
5export default function RootLayout() {
6 return <Stack />;
7}

Update index.tsx:

 1// index.tsx (apps/mobile/src/app)
 2import { Text, View } from "react-native";
 3
 4export default function Index() {
 5 return (
 6 <View className="flex-1 items-center justify-center bg-white">
 7 <Text className="text-4xl font-bold">Hello World</Text>
 8 </View>
 9 );
10}

Metro resolution fix

Running turbo dev may produce a Metro resolution error:

Metro expects a flat node_modules tree. Create .npmrc at the repo root and reinstall:

1# terminal (repo root)
2printf "node-linker=hoisted\n" > .npmrc
3rm -rf node_modules apps/**/node_modules
4pnpm install
5pnpm dev --reset-cache

node-linker=hoisted reduces symlink complexity so Metro resolves packages cleanly. Credit to this GitHub issue for the fix.

The mobile app now runs:

Align React versions

Pin React and React Native versions at the root to prevent duplicate copies and peer conflicts:

 1// package.json (repo root)
 2{
 3 "pnpm": {
 4 "overrides": {
 5 "react": "19.1.0",
 6 "react-dom": "19.1.0",
 7 "react-native": "0.81.5",
 8 "react-native-web": "0.21.1",
 9 "tailwindcss": "3.4.18"
10 }
11 }
12}

Ensure apps/web/package.json uses the same react and react-dom versions, then run pnpm install.

Set up Tailwind and NativeWind in Next.js

Install all dependencies:

1# terminal (apps/web)
2pnpm add react-native-web nativewind
3pnpm add -D tailwindcss@^3 postcss autoprefixer
4npx tailwindcss init -p

NativeWind requires Tailwind v3. If create-next-app installed v4, pin to ^3 explicitly.

Configure Tailwind with the NativeWind preset:

 1// tailwind.config.js (apps/web)
 2/** @type {import('tailwindcss').Config} */
 3import nativewindPreset from "nativewind/preset";
 4
 5module.exports = {
 6 content: ["./src/**/*.{js,jsx,ts,tsx}"],
 7 presets: [nativewindPreset],
 8 theme: {
 9 extend: {},
10 },
11 plugins: [],
12}

Configure PostCSS:

1// postcss.config.js (apps/web)
2module.exports = {
3 plugins: {
4 tailwindcss: {},
5 autoprefixer: {},
6 },
7}

Add global styles:

1/* global.css (apps/web/src/app) */
2@tailwind base;
3@tailwind components;
4@tailwind utilities;

Configure Next.js to resolve react-native to react-native-web and transpile NativeWind:

 1// next.config.ts (apps/web)
 2import type { NextConfig } from 'next'
 3
 4const nextConfig: NextConfig = {
 5 transpilePackages: [
 6 'react-native',
 7 'react-native-web',
 8 'nativewind',
 9 'react-native-css-interop',
10 ],
11 webpack: (config) => {
12 config.resolve.alias = {
13 ...(config.resolve.alias || {}),
14 'react-native$': 'react-native-web',
15 };
16 config.resolve.extensions = [
17 '.web.ts',
18 '.web.tsx',
19 '.web.js',
20 ...config.resolve.extensions,
21 ];
22 return config;
23 }
24}
25
26export default nextConfig

Enable NativeWind types in tsconfig.json:

1// tsconfig.json (apps/web)
2{
3 "compilerOptions": {
4 "jsxImportSource": "nativewind",
5 "types": ["nativewind/types"]
6 }
7}

Remove page.module.css and update page.tsx:

1// page.tsx (apps/web/src/app)
2export default function Home() {
3 return (
4 <div className="flex flex-col items-center justify-center h-screen">
5 <h1 className="text-4xl font-bold">Hello World</h1>
6 </div>
7 );
8}

Result:

Verify React Native components render through react-native-web:

 1// page.tsx (apps/web/src/app)
 2import { View, Text } from "react-native";
 3
 4export default function Home() {
 5 return (
 6 <div className="flex flex-col items-center justify-center h-screen">
 7 <h1 className="text-4xl font-bold">Hello World</h1>
 8 <View className="flex-1 items-center justify-center bg-white">
 9 <Text>Hello from React Native</Text>
10 </View>
11 </div>
12 );
13}

Shared UI package

Create a packages/ui package with reusable React Native components styled by NativeWind. Components run on web (via react-native-web) and mobile without changes.

Structure

1packages/ui/
2├── package.json
3├── tsconfig.json
4├── nativewind-env.d.ts
5└── src/
6 ├── index.ts
7 ├── Button.tsx
8 └── Text.tsx

Setup

Create the folder:

1# terminal (repo root)
2mkdir -p packages/ui/src

package.json:

 1// packages/ui/package.json
 2{
 3 "name": "ui",
 4 "version": "0.0.0",
 5 "private": true,
 6 "main": "./src/index.ts",
 7 "types": "./src/index.ts",
 8 "scripts": {
 9 "lint": "eslint",
10 "typecheck": "tsc --noEmit"
11 },
12 "devDependencies": {
13 "@types/react": "~19.0.10",
14 "eslint": "^9.25.0",
15 "eslint-config-expo": "~9.2.0",
16 "expo": "~54.0.25",
17 "nativewind": "^4.1.23",
18 "typescript": "~5.8.3"
19 },
20 "peerDependencies": {
21 "react": "19.1.0",
22 "react-native": "0.81.5"
23 }
24}

tsconfig.json:

 1// packages/ui/tsconfig.json
 2{
 3 "extends": "expo/tsconfig.base",
 4 "compilerOptions": {
 5 "strict": true,
 6 "noEmit": true
 7 },
 8 "include": [
 9 "src/**/*",
10 "nativewind-env.d.ts"
11 ]
12}

nativewind-env.d.ts:

1// packages/ui/nativewind-env.d.ts
2/// <reference types="nativewind/types" />

Components

Button.tsx:

 1// packages/ui/src/Button.tsx
 2import { Pressable, Text } from "react-native";
 3
 4export function Button({ title }: { title: string }) {
 5 return (
 6 <Pressable className="px-4 py-2 bg-blue-500 rounded">
 7 <Text className="text-white font-semibold">{title}</Text>
 8 </Pressable>
 9 );
10}

Text.tsx:

1// packages/ui/src/Text.tsx
2import { Text as RNText, TextProps } from "react-native";
3
4export function Text(props: TextProps) {
5 return <RNText className="text-base text-black" {...props} />;
6}

index.ts:

1// packages/ui/src/index.ts
2export { Button } from './Button';
3export { Text } from './Text';

The template repository includes additional components (Card, Badge, Input) with variant-based styling using tailwind-variants. The examples above are kept simple to focus on the cross-platform setup.

Integration

Add the UI package to the web app:

1// apps/web/package.json
2{
3 "dependencies": {
4 "ui": "workspace:*"
5 }
6}

Update the web Tailwind config to scan shared components:

 1// tailwind.config.js (apps/web)
 2/** @type {import('tailwindcss').Config} */
 3import nativewindPreset from "nativewind/preset";
 4
 5module.exports = {
 6 content: [
 7 "./src/**/*.{js,jsx,ts,tsx}",
 8 "../../packages/ui/src/**/*.{js,jsx,ts,tsx}"
 9 ],
10 presets: [nativewindPreset],
11}

Run pnpm install.

Usage in web

 1// apps/web/src/app/page.tsx
 2"use client"
 3
 4import { View } from "react-native";
 5import { Button, Text } from "ui";
 6
 7export default function Home() {
 8 return (
 9 <View className="flex-1 justify-center items-center h-screen">
10 <Text className="mb-4 text-xl font-bold">Welcome</Text>
11 <Button title="Get Started" />
12 </View>
13 );
14}

Result:

Usage in mobile

Add the UI package to the mobile app:

1// apps/mobile/package.json
2{
3 "dependencies": {
4 "ui": "workspace:*"
5 }
6}

Run pnpm install.

 1// apps/mobile/src/app/index.tsx
 2import { View } from "react-native";
 3import { Button, Text } from "ui";
 4
 5export default function Index() {
 6 return (
 7 <View className="flex-1 justify-center items-center bg-white">
 8 <Text className="mb-4 text-xl font-bold">Welcome</Text>
 9 <Button title="Get Started" />
10 </View>
11 );
12}

Result:

Wrapping up

That covers the core setup. Here’s what you’ve built:

1monorepo/
2├── apps/
3│ ├── web/ # Next.js with react-native-web
4│ └── mobile/ # Expo (React Native)
5├── packages/
6│ └── ui/ # Shared components
7└── turbo.json # Task orchestration

1turbo dev # Start both apps
2turbo build # Build all packages
3turbo typecheck # Type checking
4turbo lint # Lint code

The template is meant to be a starting point, so fork it and make it yours. You could add shared packages for utilities or API clients, set up shared ESLint and Prettier configs, wire up CI/CD with GitHub Actions and Turborepo remote caching, or swap NativeWind for something like Tamagui or UniWind. The template also includes a Vite + TanStack Router web app (apps/web-vite) if you prefer something lighter than Next.js.

I built this by learning as I went, piecing together docs, debugging pnpm symlinks, and figuring out which config goes where. This post and the template are my way of sharing what I learned so you can skip the parts that aren’t fun. It’s not a polished product, it’s a head start. If it saves you even an hour of setup, it was worth writing.

If you found this useful, give the repo a star. If something’s broken, open an issue.

You can also follow me on X (formerly Twitter) where I post about other things I’m working on. Speaking of which, check out my games: Hukora, a logic-based puzzle game, and Arithmego, an arithmetic game for the terminal.

Gürsel Çakar

React Monorepo from Scratch: Next.js, Expo & NativeWind

Prerequisites

Initialise the repository

Define the workspace

Add Turborepo

Add the Next.js app

Wire scripts to Turborepo

Native builds approval

First build and caching

Add the Expo app

Turborepo TUI

Install NativeWind in Expo

Metro resolution fix

Align React versions

Set up Tailwind and NativeWind in Next.js

Shared UI package

Structure

Setup

Components

Integration

Usage in web

Usage in mobile

Wrapping up