Onboarding Guide

Welcome to the cloudalt-frontend! This guide will help you get started with the project.

Prerequisites

Node.js (v18 or higher)
Yarn (v4 or higher)

Getting Started

Clone the repository:

git clone <repository-url>
cd cloudalt-frontend

Install dependencies:
Terminal window
```
yarn install
```
Important: All dependencies are centrally managed in the root package.json. Individual mobile and web apps no longer maintain their own dependencies or devDependencies. This ensures consistency across the monorepo and eliminates redundant installations.

Workspace Structure

This is an Nx workspace. Here’s a brief overview of the directory structure:

apps/: Contains all the applications.
- Each application is further divided into mobile (React Native/Expo) and web (React/Vite) projects.
packages/: Contains shared libraries and packages used across applications.
docs/: Contains documentation.
scripts/: Contains utility scripts, including:
- verify-repo.sh: Runs comprehensive workspace validation (lint, typecheck, build, cycle detection)
- check-nested-node_modules.sh: Safeguard to prevent nested dependency installations

Dependency Management

All dependencies are centralized in the root package.json. Individual app package.json files contain only:

name
version
private
scripts

This architecture ensures:

Single source of truth for all package versions
Faster installations (no redundant node_modules)
Consistent dependency resolution across all apps
Reduced repository size

⚠️ Never add dependencies or devDependencies to individual app package.json files. All packages must be added to the root.

Development

To run an application, use the nx command:

# To run a web application
yarn nx serve <app-name>-web

# To run a mobile application
yarn nx start <app-name>-mobile

For example, to run the pinkguest-web application:

yarn nx serve pinkguest-web

And to run the pinkguest-mobile application:

yarn nx start pinkguest-mobile
### Web (Vite) specifics

To keep web apps fast and isolated from React Native internals, ensure the following in each web app (e.g. `apps/.../web/`):

  - Tailwind CSS v3 PostCSS plugins in `postcss.config.js`:

  ```js
  // Tailwind v3 standard
  module.exports = {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    },
  };

Vite aliases to prevent RN code from entering the web bundle and to force the web entry of shared UI:

resolve: {
  alias: {
    'react-native$': 'react-native-web',
    'react-native-svg': 'react-native-svg-web',
    '@cloudalt-frontend/ui': '@cloudalt-frontend/ui/index.web',
  },
},
optimizeDeps: {
  exclude: ['react-native'],
},

Ensure a serve target exists in project.json using @nx/vite:dev-server so you can run:

yarn nx serve <app-name>-web

## Building Applications

To build an application for production, use the `nx` command:

```bash
# To build a web application
yarn nx build <app-name>-web

# To build a mobile application
# (Refer to Expo documentation for building and deploying mobile apps)

Running Tests

To run tests for a specific project, use the nx command:

yarn nx test <project-name>

Further Help

To get more help on the Nx CLI, check out the Nx documentation.

Verification & Quality Gates

The monorepo includes automated verification scripts to ensure code quality, dependency integrity, and build consistency.

Running Verification

To run the full verification suite:

yarn verify
# Or directly:
./scripts/verify-repo.sh

This runs the following stages:

InstallIntegrity: Verifies yarn install succeeded without errors
RegistrySchemaValidation: Validates packages/brands/registry.json against schema
BrandTypesCheck: Ensures brand types are up-to-date (not stale)
VitePathValidation: Checks Vite path configurations
ProjectTargets: Validates project.json targets
Lint: Runs eslint across the workspace
Typecheck: Runs TypeScript type checking
Build: Builds all packages
UITreeShake: Verifies web bundle doesn’t include React Native code
SizeThresholds: Checks bundle sizes against configured thresholds
BundleScan: (Placeholder for future bundle analysis)

Output: Verification results are saved to .verify/ directory:

.verify/full-output.log: Complete verification log
.verify/summary.json: Machine-readable summary with timings and status
.verify/size-results.json: Bundle size measurements

Tip: Use jq to query the summary JSON:

# Check which stages failed
jq '.stages[] | select(.status == "error")' .verify/summary.json

# Get total verification time
jq '.duration.seconds' .verify/summary.json

# Check specific stage timing
jq '.stages[] | select(.name == "Build") | .duration' .verify/summary.json

Brand Registry Scripts

Tailwind Parity Guard

Run this whenever you:

add or modify Tailwind configs (app or Storybook)
add a new UI package that uses Tailwind
see styling differences between Storybook and an app

yarn tailwind:guard

It fails the run if Tailwind versions drift, v4-only artifacts are present, or configs don’t use the expected monorepo patterns.

Generate Brand Types

Generates TypeScript types and constants from the brand registry:

yarn generate-brand-types
# Or directly:
node scripts/generate-brand-types.mjs

Output:

packages/brands/src/generated-types.ts: Brand ID types and constants
packages/brands/src/generated-constants.ts: ALL_BRAND_IDS array

When to run:

After adding/removing brands in packages/brands/registry.json
After modifying brand properties

Stale detection: The verify script automatically detects stale types. If types are out of date, verification fails with a clear error message.

Generate Brand READMEs

Generates per-brand README files with auto-generated and custom sections:

# Generate/update all brand READMEs
node scripts/generate-brand-readme.mjs

# Check mode (dry-run)
node scripts/generate-brand-readme.mjs --check

# Force overwrite (for migration)
node scripts/generate-brand-readme.mjs --force-overwrite

Protected Regions:

 to : Regenerated on every run
Custom content below auto-generated section: Preserved across regenerations

Output: apps/{family}/{brand}/mobile/README.md for each brand

Validate Brand Registry Schema

Fail-fast schema validation for the brand registry:

node scripts/validate-brand-registry.mjs

Exits with code 1 if registry.json doesn’t match the Zod schema. This runs automatically in the verify pipeline.

Quality & Performance Scripts

Check UI Tree-Shake

Verifies that the web build of @cloudalt/ui doesn’t include React Native code:

node scripts/check-ui-tree-shake.mjs

What it checks:

Web bundle (packages/ui/dist/index.web.js) for React Native imports
Native bundle size vs web bundle size
Reports size savings percentage

Expected: Web bundle should be ~50% smaller than native bundle

Check Size Thresholds

Monitors bundle sizes and enforces regression guards:

# Check sizes (warns on violations)
node scripts/check-size-thresholds.mjs

# Strict mode (fails on violations, for CI)
node scripts/check-size-thresholds.mjs --strict

Configuration: size-thresholds.json defines per-package limits:

{
  "packages/brands": {
    "softLimit": 40000,
    "hardLimit": 50000
  }
}

Output: Results saved to .verify/size-results.json

Benchmark Build Tools

Compares build tool performance (tsc vs tsup):

node scripts/benchmark-build-tools.mjs

Findings from M5:

tsc --emitDeclarationOnly is 44-138% faster than tsup
Recommendation: Use tsc for declaration-only builds

Critical Naming Convention for Mobile Apps

Problem: The default Nx Expo generator (@nx/expo:app) creates mobile applications with a generic package name ("name": "mobile") in their package.json file. This creates fatal Duplicate workspace name errors when running yarn install in a properly configured monorepo.

Policy: To prevent this, the following naming convention must be followed for all new mobile applications:

Package Name (package.json): The name must be unique across the entire workspace and follow the format app-name-platform.
- Example: For the staymatch_app mobile app, the name must be staymatch-app-mobile.
apps/stay_match/staymatch_app/mobile/package.json
```
{
  "name": "staymatch-app-mobile",
  // ...
}
```
App Name and Slug (app.json): The name and slug fields in the app.json file must also be updated to match the unique package name.
apps/stay_match/staymatch_app/mobile/app.json
```
{
  "expo": {
    "name": "staymatch-app-mobile",
    "slug": "staymatch-app-mobile",
    // ...
  }
}
```

Common Dependency Issues & Resolutions

This workspace has been configured to resolve several common dependency and peer dependency conflicts. Here are some key things to be aware of:

1. `@swc/core` Version Alignment

Problem: The version of @swc/core used by Nx and other tools can conflict with the version required by packages like @swc-node/register. This results in YN0060 peer dependency warnings during yarn install.
Resolution: The root package.json has been updated to use a specific version of @swc/core (^1.13.3) that satisfies all consumers. If you encounter this issue again, ensure the versions are aligned in the root package.json.

2. `react` and `react-dom` Peer Dependencies

Problem: Mobile applications generated with @nx/expo may not include react and react-dom in their package.json, leading to peer dependency issues.
Resolution: All mobile applications must have react and react-dom listed as dependencies. The versions have been standardized to ~18.3.1 across the workspace.

3. `SafeAreaView` Component Usage

Problem: The SafeAreaView component from react-native is deprecated and can cause layout issues.
Resolution: Always import SafeAreaView from react-native-safe-area-context. If the dependency is not present in a mobile app’s package.json, add it.
```
// Correct usage
import { SafeAreaView } from 'react-native-safe-area-context';
```

4. Workspace Integrity and Dependency Management

Problem: Incorrectly running yarn install or other package management commands from within an individual application’s directory (e.g., apps/some-app/mobile/) instead of the monorepo root can create nested node_modules folders. This leads to unpredictable builds, dependency conflicts, and errors like ENOENT: no such file or directory, uv_cwd.
Policy: All package management commands must be executed from the monorepo root (/Users/work-station/company/cloudalt/cloudalt-frontend). There should only be one node_modules directory at the top level of the workspace.
Verification and Cleanup Procedure:
1. To ensure workspace integrity, periodically verify that no nested node_modules directories exist.
2. Run the following command from the monorepo root to find any incorrect installations:
  Terminal window
```
find . -name "node_modules" -type d -maxdepth 3
```
3. If this command returns any path other than ./node_modules, those directories are incorrect and must be deleted immediately. For example:
  Terminal window
```
# This indicates a problem
./apps/some-app/mobile/node_modules

# To fix, run:
rm -rf ./apps/some-app/mobile/node_modules
```
4. After cleanup, run a single yarn install from the monorepo root to ensure the workspace is in a correct and stable state.

Xcode Environment Setup: Offloading Data Directories to External SSD

Note for Developers & GitHub Copilot:

We have relocated Xcode’s build artifacts, cache directories, and archives from the default system drive to an external SSD (T7). This change was implemented to optimize disk usage and improve overall build performance.

DerivedData is now stored at: /Volumes/T7/XcodeDerivedData
Archives are now stored at: /Volumes/T7/XcodeArchives
CompilationCache.noindex is now stored at: /Volumes/T7/XcodeCompilationCache.noindex

This setup uses symbolic links, so Xcode continues to reference the usual ~/Library/Developer/Xcode/ folders, while files are physically stored on the external drive. Future build, cache, and archive data will be preserved externally.

Important: Please ensure that the T7 drive is always mounted and available when working in Xcode, or resolving build and archive artifacts. If the drive is not present, Xcode will be unable to access these directories.

This setup benefits disk space and performance for larger projects and is safe for day-to-day development workflows.

Asset Management

All assets in the monorepo follow a two-tier organization system to optimize bundle sizes and maintain clear ownership boundaries.

Monorepo-Wide Assets (`packages/assets/`)

Use for: Generic icons, illustrations, and company branding used across ALL apps.

Structure:

packages/assets/
├── icons/
│   ├── arrows/       # Navigation arrows
│   ├── actions/      # Action icons (plus, trash, edit)
│   ├── navigation/   # Nav icons (home, menu, back)
│   └── social/       # Social media icons
├── illustrations/    # Generic empty states, errors
└── brand/logo/       # CloudAlt company logo

Guidelines:

Keep this directory minimal - assets here are bundled with ALL apps
Only generic, truly universal assets belong here
SVG format preferred for icons (< 5KB each)
All assets must work for every brand

Brand-Specific Assets (`apps/{division}/{brand}/shared/assets/`)

Use for: Images, fonts, and assets unique to a specific brand.