This guide will walk you through setting up the FE Monorepo and running all three applications: the React SPA, Next.js web app, and Expo mobile app.
Prerequisites
Before you begin, ensure you have the following installed:
- Node.js >= 24.14.0
- Bun 1.3.10 or later
- Git for version control
The monorepo uses Bun as its package manager. If you don’t have Bun installed, visit bun.sh for installation instructions. Installation
Clone the repository
Clone the repository to your local machine:git clone <your-repo-url>
cd fe-monorepo
Install dependencies
Install all dependencies for the monorepo using Bun:This command will install dependencies for all apps and packages in the workspace. Set up environment variables
Each app requires environment variables for configuration. Copy the example files and configure them:cd apps/spa
cp .env.dev.example .env.dev
# Edit .env.dev with your configuration
cd apps/web
cp .env.dev.example .env.dev
# Edit .env.dev with your configuration
cd apps/expo
# Pull environment variables from EAS
bun env:pull:dev
Never commit .env.dev or .env.prod files to version control. These files contain sensitive information.
Running the applications
You can run each application independently from the monorepo root.
React SPA
The Single Page Application runs on port 3001 and uses React 19 with TanStack Router.
The SPA uses Vite for blazing-fast development with Hot Module Replacement (HMR).
Next.js Web App
The full-stack Next.js app runs on port 3002 and includes server-side rendering, API routes, and database integration.
Database setup for Web app
The Web app uses Drizzle ORM with PostgreSQL. You’ll need to set up your database:# Generate database schema
bun web db:gen
# Push schema to database
bun web db:push
# Open Drizzle Studio to manage your database
bun web db:studio
Expo Mobile App
The React Native app uses Expo 53 with development builds.
Expo requires additional setup. You need Java 17+ and EAS CLI installed globally. See the Expo documentation for platform-specific requirements. Create a development build
For the first time, you need to create a development build:bun expo prebuild
bun expo build:android:dev:local
Start the development server
Once you have the development build installed on your device/simulator:This starts the Metro bundler. Scan the QR code with your development build app. You only need to rebuild when you:
- Install native dependencies
- Change
app.json configuration
- Upgrade Expo SDK
Running from app directories
You can also run commands from within each app directory:
# Navigate to the app
cd apps/spa
# Run commands directly
bun dev
bun build
bun typecheck
Development workflow
Here are common development tasks you’ll perform:
Type checking
Run type checking across all apps:
Or for a specific app:
bun spa:typecheck
bun web:typecheck
bun expo:typecheck
Linting
The monorepo uses ESLint with a shared configuration:
Testing
Each app has its own test suite using Playwright (web apps) or Maestro (Expo):
# Run tests (requires dev server running)
bun spa test
# Run tests with UI
bun spa test:ui
# Install test browsers
bun spa test:install
# Run tests (requires dev server running)
bun web test
# Run tests with UI
bun web test:ui
# Install test browsers
bun web test:install
# Run E2E tests on development build
bun expo test:dev
# Run E2E tests on production build
bun expo test:prod
# Open Maestro Studio
bun expo test:ui
Upgrading dependencies
Always use exact versions for dependencies in this monorepo.
# Check for outdated dependencies
bun bump:deps
# Install updates
bun install
# Verify everything works
bun lint-typecheck
bun spa test
bun web test
Using shared packages
The monorepo includes shared packages that all apps can use:
@workspace/core
Shared business logic, types, hooks, and utilities for browser and mobile apps:
// Import from the core package
import { errorResponseSchema } from '@workspace/core/apis/core'
import type { ErrorResponseSchema } from '@workspace/core/types/api'
// Available exports:
// - apis/* - API schemas and types
// - constants/* - Shared constants
// - hooks/* - React hooks
// - libs/* - Utility libraries
// - services/* - Business logic
// - types/* - TypeScript types
// - utils/* - Helper functions
@workspace/typescript-config
Shared TypeScript configuration used across all apps and packages:
{
"extends": "@workspace/typescript-config/base.json"
}
Next steps
Now that you have your development environment running:
Architecture
Learn about the monorepo structure and how packages are organized
SPA Guide
Deep dive into the React SPA architecture and features
Web Guide
Explore the Next.js app with SSR and API routes
Expo Guide
Build native mobile apps with Expo and React Native
Troubleshooting
If you see an error about a port being in use:# Find and kill the process using the port
lsof -ti:3001 | xargs kill -9 # for SPA
lsof -ti:3002 | xargs kill -9 # for Web
Dependency installation fails
Clear the Bun cache and reinstall:bun pm cache rm
bun install
Clean install from scratch
If you encounter persistent issues, perform a clean installation:This removes all node_modules, build artifacts, and caches, then reinstalls everything.
For Expo-specific issues:# Check for known issues
cd apps/expo
bun expo doctor
# Clean prebuild
bun prebuild
