Skip to main content

​
Overview

The FE Monorepo follows a strict dependency management strategy:
  • Always use EXACT versions (no ^ or ~ ranges)
  • Use bun bump:deps for automated dependency updates
  • Special process for Expo SDK upgrades
  • Verify changes with testing and building
Always use exact versions for dependencies to ensure reproducible builds across environments.

​
Upgrading Non-Expo Dependencies

For all packages except Expo-related ones, use the automated upgrade command.

​
Step-by-Step Process

1

Check for Outdated Dependencies

Run the bump command to check and update dependencies:
bun bump:deps
This command:
  • Checks for outdated dependencies across all workspace packages
  • Updates to the latest versions
  • Excludes Expo-related packages (handled separately)
  • Updates peer dependencies
2

Install Updated Dependencies

Install the updated dependencies:
bun install
3

Handle Playwright Upgrades

If Playwright had a MINOR version upgrade, install the new browser:
bun spa test:install
4

Run Tests

Run E2E tests to ensure everything works:
bun spa test
bun web test
bun expo test:dev  # Start dev server and emulator first
5

Build All Apps

Build all apps with development environment:
bun spa build
bun web build
bun expo build:android:dev:local
6

Lint and Type Check

Verify linting and type checking:
bun lint-typecheck

​
Excluded Packages

The bump:deps command excludes Expo-related packages:
  • expo*
  • @expo*
  • @dev-plugins*
  • @babel*
  • metro*
  • react-native*
  • @react-navigation*
  • tamagui
  • @tamagui*
These packages require coordinated upgrades with the Expo SDK version.

​
Upgrading Expo Dependencies

Expo apps require a special upgrade process to ensure compatibility.
Always check the Expo SDK changelog for breaking changes before upgrading.

​
Step-by-Step Process

1

Check Expo SDK Changelog

Review the changelog for the target Expo SDK version:
  • Check the “Deprecations, renamings, and removals” section
  • Note any breaking changes that might affect your app
  • Plan necessary code changes
2

Upgrade Expo SDK

Run the Expo upgrade command:
cd apps/expo
npx expo install expo@^53.0.0 --fix
Replace 53.0.0 with your target SDK version.
The --fix flag automatically updates all Expo-related packages to compatible versions.
3

Run Expo Doctor

Check for known issues and compatibility problems:
bun expo doctor
Fix any issues reported by the doctor.
4

Update EAS CLI Version

Update the cli.version in eas.json to match the latest EAS CLI:
eas.json
{
  "cli": {
    "version": ">= 13.0.0"
  }
}
5

Upgrade Development Tools

If required by the new SDK:
  • Update Xcode (for iOS)
  • Update Android Studio (for Android)
  • Update Java version if needed
6

Regenerate Native Projects

Clean and regenerate the native projects:
bun expo prebuild
7

Create Development Build

Build the app locally to test:
bun expo build:android:dev:local
8

Test the App

Install and test the app:
bun expo dev
bun expo test:dev  # After installing the build

​
Detailed Expo Upgrade Guide

For more details, see the Expo app README.

​
Upgrading IntentUI Components

The monorepo uses IntentUI components which require special handling:
1

Run Interactive Update

bunx @intentui/cli@latest add -o
The -o flag overwrites existing components.
2

Manual Adjustments

After the update:
  1. Copy prop changes into providers/toast/context.tsx
  2. Remove the generated toast.tsx file if needed
  3. Use react-stately instead of @react-stately/color
  4. Use react-aria instead of @react-aria/i18n
3

Alternative: Use Shorthand Command

bun bump:ui
This runs the same command with the correct configuration.

​
Version Management with Changesets

After upgrading dependencies and verifying everything works:
1

Create Changeset

Document the changes:
bun cs
Follow the prompts to:
  • Select affected packages
  • Choose version bump type (major, minor, patch)
  • Describe the changes
2

Version the Changeset

Update package versions:
bun cs:v

​
Verification Checklist

After upgrading dependencies, ensure you complete all verification steps:
1

Run All Tests

bun spa test
bun web test
bun expo test:dev
2

Build All Apps

bun spa build
bun web build
bun expo build:android:dev:local
3

Lint and Type Check

bun lint-typecheck
4

Test in Browser/Emulator

Manually test critical user flows in:
  • SPA (bun spa dev)
  • Web (bun web dev)
  • Expo (on device/simulator)

​
Troubleshooting

​
Dependency Conflicts

Peer dependency warnings:
  1. Check if the warning is critical
  2. Try updating peer dependencies: bun bump:deps includes --peer
  3. Manual resolution may be needed for some packages
Version incompatibilities:
  1. Check package changelogs for breaking changes
  2. Look for migration guides
  3. Consider pinning to a compatible version temporarily

​
Build Failures After Upgrade

Type errors:
  1. Check for breaking type changes in updated packages
  2. Update type imports if packages changed structure
  3. Run bun lint-typecheck to see all errors
Runtime errors:
  1. Check browser console / app logs
  2. Review breaking changes in package changelogs
  3. Test with development builds first

​
Expo-Specific Issues

Native build fails:
  1. Ensure Xcode/Android Studio are up to date
  2. Run bun expo doctor for diagnostics
  3. Clean and rebuild: bun expo prebuild
Version mismatches:
  1. Run bun expo install:check to check compatibility
  2. Run bun expo install:fix to fix version mismatches

​
Best Practices

Upgrade Strategy:
  • Upgrade dependencies regularly (weekly or bi-weekly)
  • Test thoroughly after each upgrade
  • Use exact versions to prevent surprises
  • Read changelogs before upgrading major versions
  • Upgrade one major package at a time for easier debugging

​
Safety First

  1. Branch Protection: Always upgrade on a feature branch
  2. Test Coverage: Run full test suite before merging
  3. Incremental Changes: Upgrade one package at a time for major versions
  4. Documentation: Use changesets to document what changed and why

​
Monitoring

  • Check for security vulnerabilities: bun audit
  • Review dependabot/renovate PRs regularly
  • Monitor package deprecation notices

​
Quick Reference

TaskCommand
Update all non-Expo depsbun bump:deps
Update Expo SDKnpx expo install expo@^XX.0.0 --fix
Update IntentUIbun bump:ui
Install dependenciesbun install
Check Expo compatibilitybun expo doctor
Fix Expo versionsbun expo install:fix
Create changesetbun cs
Version changesetbun cs:v
Run all testsbun spa test && bun web test
Lint and type checkbun lint-typecheck

Build docs developers (and LLMs) love

Get started for freeTalk to us