Skip to main content

​
Overview

The FE Monorepo uses Bun as the package manager and includes three main applications: SPA (React), Web (Next.js), and Expo (React Native). This guide covers the essential development workflows for working with the monorepo.

​
Prerequisites

  • Node.js 24.14.0 or higher
  • Bun 1.3.10 or higher
  • For Expo development: Java 17+, EAS CLI (npm i -g eas-cli)

​
Running Applications

​
SPA Application (Port 3001)

The SPA is a React 19 application built with Vite and TanStack Router. 
bun spa dev

​
Web Application (Port 3002)

The Web app is a Next.js 16 full-stack application. 
bun web dev

​
Expo Application

The Expo app is a React Native application built with Expo 53.
1

Pull Environment Variables

Pull EAS project environment variables to your local environment:
bun expo env:pull:dev
2

Prebuild Native Projects

Generate native projects (Android/iOS folders) - required when changing app.json or installing native libraries:
cd apps/expo
bun prebuild
3

Create Development Build

Build the app for your platform:
bun build:android:dev:local
4

Start Development Server

Run the development server:
bun expo dev
For iOS simulator builds, you’ll get a .tar.gz file. Install it using bun expo ios:sim:install.
Don’t use VPN when developing Expo apps, or fetch will not work properly.

​
Linting and Type Checking

​
Lint All Packages

# Run ESLint on all packages
bun lint

# Auto-fix linting issues
bun lint:fix

# Inspect ESLint configuration
bun lint:inspector

​
Type Check All Apps

# Type check all apps in parallel
bun typecheck

# Type check individual apps
bun spa:typecheck
bun web:typecheck
bun expo:typecheck

# Run both lint and typecheck together
bun lint-typecheck

​
Monorepo Commands

The monorepo uses Bun workspaces with filter commands for running scripts in specific packages.

​
Workspace Filters

# Run any SPA script (with better logging)
bun spa <script-name>

# Example: build the SPA
bun spa build

​
CI Filters

For CI environments, use the CI-specific filters that omit the --elide-lines=0 flag: 
bun spa:ci <script-name>
bun web:ci <script-name>
bun expo:ci <script-name>

​
Database Management (Web App)

The Web app uses Drizzle ORM with PostgreSQL.
1

Generate Auth Schema

Generate Better Auth schema:
bun web auth:gen
2

Push Schema Changes

Push schema changes to database:
bun web db:push
3

Open Drizzle Studio

Open the database GUI at http://localhost:3003:
bun web db:studio

​
Observability

The monorepo includes OpenTelemetry integration with Grafana for observability.
1

Start Grafana Stack

Run the Grafana LGTM container (Prometheus, Tempo, Loki, Pyroscope):
bun compose:up
2

Access Dashboard

Open Grafana dashboard at http://localhost:3111:
  • Username: admin
  • Password: admin

​
Cleaning the Monorepo

Remove all build artifacts, dependencies, and caches: 
bun clean
This command removes node_modules, build outputs, and locks. You’ll need to run bun install afterwards.

​
Development Tips

  • Always use exact versions for dependencies
  • For Expo, regenerate native projects (bun prebuild) when changing app.json or installing native libraries
  • Use bun --parallel prefix to run multiple scripts concurrently
  • The source of truth for environment variables is local .env files for SPA/Web, and EAS project environment for Expo

​
Quick Reference

TaskCommand
Install dependenciesbun install
Run SPA dev serverbun spa dev
Run Web dev serverbun web dev
Run Expo dev serverbun expo dev
Lint all packagesbun lint
Type check all appsbun typecheck
Clean monorepobun clean
Build SPAbun spa build
Build Webbun web build
Build Expo (Android)bun expo build:android:dev:local

Build docs developers (and LLMs) love

Get started for freeTalk to us