Rork × Turborepo Monorepo Architecture: Managing Shared Code and Type-Safe Libraries Across Multiple Apps

{
  "name": "my-rork-apps",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "devDependencies": {
    "turbo": "^2.0.0",
    "typescript": "^5.4.0"
  },
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "type-check": "turbo run type-check",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "packageManager": "npm@10.0.0"
}

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".expo/**"],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "cache": true
    },
    "clean": {
      "cache": false
    }
  }
}

{
  "name": "@my-apps/ui",
  "version": "0.0.1",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "scripts": {
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "peerDependencies": {
    "react": "*",
    "react-native": "*"
  },
  "devDependencies": {
    "@my-apps/config": "*",
    "react": "^18.2.0",
    "react-native": "^0.74.0"
  }
}

// packages/ui/src/components/Button.tsx
import React from 'react';
import {
  TouchableOpacity,
  Text,
  ActivityIndicator,
  StyleSheet,
  ViewStyle,
  TextStyle,
} from 'react-native';
 
export type ButtonVariant = 'primary' | 'secondary' | 'danger' | 'ghost';
export type ButtonSize = 'sm' | 'md' | 'lg';
 
interface ButtonProps {
  onPress: () => void;
  title: string;
  variant?: ButtonVariant;
  size?: ButtonSize;
  loading?: boolean;
  disabled?: boolean;
  style?: ViewStyle;
  textStyle?: TextStyle;
}
 
// A single source of truth for button design across all your apps
export const Button: React.FC<ButtonProps> = ({
  onPress,
  title,
  variant = 'primary',
  size = 'md',
  loading = false,
  disabled = false,
  style,
  textStyle,
}) => {
  const isDisabled = disabled || loading;
 
  return (
    <TouchableOpacity
      onPress={onPress}
      disabled={isDisabled}
      style={[
        styles.base,
        styles[variant],
        styles[`size_${size}`],
        isDisabled && styles.disabled,
        style,
      ]}
      activeOpacity={0.8}
    >
      {loading ? (
        <ActivityIndicator
          color={variant === 'primary' ? '#ffffff' : '#6366f1'}
          size="small"
        />
      ) : (
        <Text style={[styles.text, styles[`text_${variant}`], textStyle]}>
          {title}
        </Text>
      )}
    </TouchableOpacity>
  );
};
 
const styles = StyleSheet.create({
  base: {
    borderRadius: 12,
    alignItems: 'center',
    justifyContent: 'center',
    flexDirection: 'row',
  },
  primary: { backgroundColor: '#6366f1' },
  secondary: {
    backgroundColor: '#f1f5f9',
    borderWidth: 1,
    borderColor: '#e2e8f0',
  },
  danger: { backgroundColor: '#ef4444' },
  ghost: { backgroundColor: 'transparent' },
  disabled: { opacity: 0.5 },
  size_sm: { paddingHorizontal: 12, paddingVertical: 8, minHeight: 36 },
  size_md: { paddingHorizontal: 16, paddingVertical: 12, minHeight: 44 },
  size_lg: { paddingHorizontal: 24, paddingVertical: 16, minHeight: 52 },
  text: { fontWeight: '600', fontSize: 15 },
  text_primary: { color: '#ffffff' },
  text_secondary: { color: '#374151' },
  text_danger: { color: '#ffffff' },
  text_ghost: { color: '#6366f1' },
});

// packages/ui/src/index.ts
export { Button } from './components/Button';
export type { ButtonVariant, ButtonSize } from './components/Button';
 
export { Card } from './components/Card';
export { Input } from './components/Input';
export { Avatar } from './components/Avatar';
export { Badge } from './components/Badge';
export { Modal } from './components/Modal';
export { Toast, useToast } from './components/Toast';
export { LoadingSpinner } from './components/LoadingSpinner';
export { EmptyState } from './components/EmptyState';
 
// Design tokens
export { colors } from './theme/colors';
export { spacing } from './theme/spacing';
export { typography } from './theme/typography';

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  displayName: string;
  avatarUrl?: string;
  createdAt: string;
  subscription: SubscriptionTier;
}
 
export type SubscriptionTier = 'free' | 'pro' | 'premium';
 
// Utility types derived from the base User type
export type CreateUserInput = Omit<User, 'id' | 'createdAt'>;
export type UpdateUserInput = Partial<Omit<User, 'id' | 'createdAt'>>;

// packages/types/src/api.ts
 
// Standardized API response envelope
export interface ApiResponse<T> {
  data: T;
  error: null;
  status: 'success';
}
 
export interface ApiError {
  data: null;
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
  status: 'error';
}
 
export type ApiResult<T> = ApiResponse<T> | ApiError;
 
// Paginated list responses
export interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  limit: number;
  hasMore: boolean;
}

// apps/app-a/app/(tabs)/profile.tsx
import { User, UpdateUserInput } from '@my-apps/types';
import { Button } from '@my-apps/ui';
 
// Type errors are caught at build time — no more runtime surprises
const updateProfile = async (input: UpdateUserInput): Promise<User> => {
  // ...
};

// packages/hooks/src/useAuth.ts
import { useState, useEffect, useCallback } from 'react';
import AsyncStorage from '@react-native-async-storage/async-storage';
import type { User } from '@my-apps/types';
 
const AUTH_TOKEN_KEY = '@auth_token';
const AUTH_USER_KEY = '@auth_user';
 
interface AuthState {
  user: User | null;
  token: string | null;
  isLoading: boolean;
  isAuthenticated: boolean;
}
 
interface UseAuthReturn extends AuthState {
  signIn: (email: string, password: string) => Promise<void>;
  signOut: () => Promise<void>;
  updateUser: (updates: Partial<User>) => void;
}
 
// Factory function: each app provides only its API base URL
// The entire auth logic is shared automatically
export const createUseAuth = (apiBaseUrl: string) => {
  return (): UseAuthReturn => {
    const [state, setState] = useState<AuthState>({
      user: null,
      token: null,
      isLoading: true,
      isAuthenticated: false,
    });
 
    // Restore session from storage on mount
    useEffect(() => {
      const restoreSession = async () => {
        try {
          const [token, userJson] = await AsyncStorage.multiGet([
            AUTH_TOKEN_KEY,
            AUTH_USER_KEY,
          ]);
          const storedToken = token[1];
          const storedUser = userJson[1] ? JSON.parse(userJson[1]) : null;
 
          if (storedToken && storedUser) {
            setState({
              user: storedUser,
              token: storedToken,
              isLoading: false,
              isAuthenticated: true,
            });
          } else {
            setState(prev => ({ ...prev, isLoading: false }));
          }
        } catch {
          setState(prev => ({ ...prev, isLoading: false }));
        }
      };
      restoreSession();
    }, []);
 
    const signIn = useCallback(async (email: string, password: string) => {
      const response = await fetch(`${apiBaseUrl}/auth/sign-in`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password }),
      });
 
      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || 'Sign-in failed');
      }
 
      const { user, token } = await response.json();
 
      await AsyncStorage.multiSet([
        [AUTH_TOKEN_KEY, token],
        [AUTH_USER_KEY, JSON.stringify(user)],
      ]);
 
      setState({ user, token, isLoading: false, isAuthenticated: true });
    }, []);
 
    const signOut = useCallback(async () => {
      await AsyncStorage.multiRemove([AUTH_TOKEN_KEY, AUTH_USER_KEY]);
      setState({ user: null, token: null, isLoading: false, isAuthenticated: false });
    }, []);
 
    const updateUser = useCallback((updates: Partial<User>) => {
      setState(prev => ({
        ...prev,
        user: prev.user ? { ...prev.user, ...updates } : null,
      }));
    }, []);
 
    return { ...state, signIn, signOut, updateUser };
  };
};

// apps/app-a/lib/auth.ts — wire up for this app's API
import { createUseAuth } from '@my-apps/hooks';
export const useAuth = createUseAuth('https://api.app-a.com');

// apps/app-b/lib/auth.ts — same logic, different endpoint
import { createUseAuth } from '@my-apps/hooks';
export const useAuth = createUseAuth('https://api.app-b.com');

// packages/hooks/src/useNetworkStatus.ts
import { useState, useEffect } from 'react';
import NetInfo, { NetInfoState } from '@react-native-community/netinfo';
 
interface NetworkStatus {
  isConnected: boolean;
  isInternetReachable: boolean | null;
  connectionType: string | null;
}
 
export const useNetworkStatus = (): NetworkStatus => {
  const [status, setStatus] = useState<NetworkStatus>({
    isConnected: true,
    isInternetReachable: null,
    connectionType: null,
  });
 
  useEffect(() => {
    NetInfo.fetch().then((state: NetInfoState) => {
      setStatus({
        isConnected: state.isConnected ?? true,
        isInternetReachable: state.isInternetReachable,
        connectionType: state.type,
      });
    });
 
    const unsubscribe = NetInfo.addEventListener((state: NetInfoState) => {
      setStatus({
        isConnected: state.isConnected ?? true,
        isInternetReachable: state.isInternetReachable,
        connectionType: state.type,
      });
    });
 
    return unsubscribe;
  }, []);
 
  return status;
};

{
  "name": "@my-apps/app-a",
  "version": "1.0.0",
  "main": "expo-router/entry",
  "scripts": {
    "dev": "expo start",
    "build:ios": "eas build --platform ios",
    "build:android": "eas build --platform android",
    "lint": "eslint .",
    "type-check": "tsc --noEmit"
  },
  "dependencies": {
    "@my-apps/ui": "*",
    "@my-apps/hooks": "*",
    "@my-apps/types": "*",
    "expo": "^52.0.0",
    "expo-router": "^4.0.0",
    "react": "^18.2.0",
    "react-native": "^0.76.0"
  },
  "devDependencies": {
    "@my-apps/config": "*"
  }
}

// apps/app-a/metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { FileStore } = require('metro-cache');
const path = require('path');
 
const projectRoot = __dirname;
const workspaceRoot = path.resolve(projectRoot, '../..');
 
const config = getDefaultConfig(projectRoot);
 
// Watch the entire workspace, not just this app's directory
config.watchFolders = [workspaceRoot];
 
// Resolve modules from both the app's and workspace's node_modules
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(workspaceRoot, 'node_modules'),
];
 
// Metro cache that cooperates with Turborepo's cache
config.cacheStores = [
  new FileStore({
    root: path.join(projectRoot, 'node_modules/.cache/metro'),
  }),
];
 
module.exports = config;

// apps/app-a/tsconfig.json
{
  "extends": "@my-apps/config/typescript/expo.json",
  "compilerOptions": {
    "paths": {
      "@my-apps/ui": ["../../packages/ui/src/index.ts"],
      "@my-apps/hooks": ["../../packages/hooks/src/index.ts"],
      "@my-apps/types": ["../../packages/types/src/index.ts"]
    }
  },
  "include": ["**/*.ts", "**/*.tsx"]
}

# Log in to Turborepo via Vercel
npx turbo login
 
# Link this repo to remote caching
npx turbo link

{
  "$schema": "https://turborepo.org/schema.json",
  "remoteCache": {
    "enabled": true,
    "signature": true
  },
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".expo/**"],
      "cache": true,
      "env": ["NODE_ENV", "EXPO_PUBLIC_API_URL"]
    }
  }
}

# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  lint-and-type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Lint all workspaces
        run: npx turbo run lint
        env:
          # Remote cache cuts repeat CI runs by up to 80%
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
 
      - name: Type check all workspaces
        run: npx turbo run type-check
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

// packages/config/src/env.ts
// Shared environment variable schema with build-time validation
 
interface BaseEnvSchema {
  EXPO_PUBLIC_API_URL: string;
  EXPO_PUBLIC_APP_ENV: 'development' | 'staging' | 'production';
}
 
export const createEnv = <T extends BaseEnvSchema>(
  schema: Record<keyof T, { required: boolean; default?: string }>
): T => {
  const env = {} as T;
 
  for (const [key, config] of Object.entries(schema)) {
    const value = process.env[key] ?? config.default;
 
    if (config.required && !value) {
      throw new Error(
        `Required environment variable "${key}" is missing. ` +
        `Check your .env file.`
      );
    }
 
    (env as Record<string, unknown>)[key] = value;
  }
 
  return env;
};

// apps/app-a/lib/env.ts
import { createEnv } from '@my-apps/config';
 
export const env = createEnv({
  EXPO_PUBLIC_API_URL: { required: true },
  EXPO_PUBLIC_APP_ENV: { required: true, default: 'development' },
  EXPO_PUBLIC_STRIPE_KEY: { required: true },
});
// Missing env vars are caught immediately at build time — not at runtime

# Build only what changed since the last commit
npx turbo run build --filter="...[HEAD^1]"
# If packages/ui changed: builds app-a, app-b, and packages/ui
# If only packages/hooks changed: skips ui, builds affected apps only
 
# Build a specific app and all its dependency packages
npx turbo run build --filter="@my-apps/app-a..."
# → Builds: packages/ui, packages/hooks, packages/types, then app-a

// packages/api/src/client.ts
import type { ApiResult } from '@my-apps/types';
 
interface ClientConfig {
  baseUrl: string;
  getToken: () => string | null;
  onUnauthorized?: () => void;
}
 
export class ApiClient {
  private config: ClientConfig;
 
  constructor(config: ClientConfig) {
    this.config = config;
  }
 
  private async request<T>(
    path: string,
    options: RequestInit = {}
  ): Promise<ApiResult<T>> {
    const token = this.config.getToken();
 
    const headers: HeadersInit = {
      'Content-Type': 'application/json',
      ...options.headers,
    };
 
    if (token) {
      (headers as Record<string, string>)['Authorization'] = `Bearer ${token}`;
    }
 
    try {
      const response = await fetch(`${this.config.baseUrl}${path}`, {
        ...options,
        headers,
      });
 
      // Handle 401 globally — trigger sign-out across the app
      if (response.status === 401) {
        this.config.onUnauthorized?.();
        return {
          data: null,
          error: { code: 'UNAUTHORIZED', message: 'Session expired' },
          status: 'error',
        };
      }
 
      const json = await response.json();
 
      if (!response.ok) {
        return {
          data: null,
          error: {
            code: json.code || 'API_ERROR',
            message: json.message || 'An unexpected error occurred',
          },
          status: 'error',
        };
      }
 
      return { data: json, error: null, status: 'success' };
    } catch (err) {
      return {
        data: null,
        error: {
          code: 'NETWORK_ERROR',
          message: 'Network request failed. Check your connection.',
        },
        status: 'error',
      };
    }
  }
 
  get<T>(path: string) {
    return this.request<T>(path, { method: 'GET' });
  }
 
  post<T>(path: string, body: unknown) {
    return this.request<T>(path, {
      method: 'POST',
      body: JSON.stringify(body),
    });
  }
 
  put<T>(path: string, body: unknown) {
    return this.request<T>(path, {
      method: 'PUT',
      body: JSON.stringify(body),
    });
  }
 
  delete<T>(path: string) {
    return this.request<T>(path, { method: 'DELETE' });
  }
}

// apps/app-a/lib/api.ts
import { ApiClient } from '@my-apps/api';
import AsyncStorage from '@react-native-async-storage/async-storage';
 
let tokenCache: string | null = null;
 
export const apiClient = new ApiClient({
  baseUrl: process.env.EXPO_PUBLIC_API_URL!,
  getToken: () => tokenCache,
  onUnauthorized: () => {
    // Clear token cache and navigate to sign-in
    tokenCache = null;
    // router.replace('/sign-in')
  },
});
 
// Keep the in-memory token cache in sync with storage
export const setApiToken = (token: string | null) => {
  tokenCache = token;
};

// Usage in any screen — identical pattern across app-a and app-b
import { apiClient } from '@/lib/api';
import type { User } from '@my-apps/types';
 
const fetchProfile = async () => {
  const result = await apiClient.get<User>('/users/me');
 
  if (result.status === 'error') {
    // Handle error with typed error code
    console.error(result.error.code, result.error.message);
    return;
  }
 
  // result.data is typed as User — no casting needed
  setUser(result.data);
};

// packages/ui/src/theme/colors.ts
export const colors = {
  // Brand palette
  primary: {
    50:  '#eef2ff',
    100: '#e0e7ff',
    500: '#6366f1',
    600: '#4f46e5',
    700: '#4338ca',
  },
  // Semantic colors
  semantic: {
    success: '#10b981',
    warning: '#f59e0b',
    error:   '#ef4444',
    info:    '#3b82f6',
  },
  // Neutral grays
  gray: {
    50:  '#f9fafb',
    100: '#f3f4f6',
    200: '#e5e7eb',
    300: '#d1d5db',
    400: '#9ca3af',
    500: '#6b7280',
    600: '#4b5563',
    700: '#374151',
    800: '#1f2937',
    900: '#111827',
  },
  // Background/surface tokens
  background: {
    primary:   '#ffffff',
    secondary: '#f9fafb',
    tertiary:  '#f3f4f6',
  },
} as const;
 
export type ColorToken = typeof colors;

// packages/ui/src/theme/spacing.ts
export const spacing = {
  xs:  4,
  sm:  8,
  md:  16,
  lg:  24,
  xl:  32,
  '2xl': 48,
  '3xl': 64,
} as const;

# Install Changesets
npm install --save-dev @changesets/cli -w
 
# Initialize (run once)
npx changeset init

# When you make a meaningful change to packages/ui
npx changeset
# Prompts: which package changed? what kind of bump? what's the summary?
# Creates a .changeset/*.md file — commit this with your code change

# When ready to release updated packages
npx changeset version  # Updates package versions + CHANGELOG.md
npx changeset publish  # Publishes to npm (skip if only using workspace packages)