carry-your-live/QUICKSTART.md

Quick Start Guide

Prerequisites Checklist

• Node.js 20+ installed
• npm 10+ installed
• Expo CLI: npm install -g expo-cli
• EAS CLI: npm install -g eas-cli (for builds)
• Git installed
• iOS Simulator (Mac) or Android Studio for mobile testing
• VS Code recommended with extensions:
  • Expo Tools
  • TypeScript Hero
  • React Native Tools
  • Prettier

---

1. Clone & Install

# Clone repository
git clone <repository-url>
cd carry-your-live

# Install dependencies
cd carry-your-live
npm install

# Verify installation
npx expo-doctor

---

2. Environment Setup

Create .env file in project root:

# API Configuration
EXPO_PUBLIC_API_URL=http://localhost:3000/api

# Optional: Analytics, crash reporting
EXPO_PUBLIC_SENTRY_DSN=
EXPO_PUBLIC_AMPLITUDE_KEY=

---

3. Run Development Server

Terminal 1: Start Metro Bundler

npx expo start

Terminal 2: Run on Platform

# iOS Simulator (Mac only)
npx expo start --ios

# Android Emulator
npx expo start --android

# Web Browser
npx expo start --web

# Physical device (scan QR code with Expo Go)
npx expo start --tunnel

---

4. Project Structure Quick Reference

carry-your-live/
├── app/                    # Expo Router screens
│   ├── _layout.tsx         # Root layout + providers
│   ├── (tabs)/             # Tab screens
│   │   ├── index.tsx       # Tasks list
│   │   ├── calendar.tsx    # Calendar view
│   │   └── settings.tsx    # Settings
│   └── add-task.tsx        # Add/edit task modal
├── src/
│   ├── components/         # Reusable UI
│   ├── database/           # WatermelonDB setup
│   ├── hooks/              # React hooks
│   ├── models/             # Database models
│   ├── constants/          # Config values
│   └── types/              # TypeScript types

---

5. Key Commands

# Development
npx expo start              # Start dev server
npx expo start -c           # Clear cache & start
npx expo start --ios        # iOS simulator
npx expo start --android    # Android emulator
npx expo start --web        # Web browser

# Code Quality
npx tsc --noEmit            # Type check
npx expo lint               # Lint
npm run format              # Format with Prettier

# Database
npx expo run:ios            # Build & run native iOS
npx expo run:android        # Build & run native Android

# Build
eas build --platform ios    # iOS build
eas build --platform android # Android build
eas build --platform web    # Web build

# Database inspection (development)
# Open in browser: chrome://inspect/#devices
# Or use React Native Debugger

---

6. Common Development Tasks

Add a New Screen

1. Create file in app/ (e.g., app/profile.tsx)
2. Export default component
3. Add to navigation in app/(tabs)/_layout.tsx or as modal in app/_layout.tsx

Add a Database Field

1. Update schema in src/database/schema.ts
2. Update model in src/models/
3. Create migration in src/database/migrations.ts
4. Update forms/components to use new field

Add a Category

Edit src/constants/index.ts:

export const DEFAULT_CATEGORIES = [
  // ... existing
  { name: 'Travel', color: '#00BCD4', order: 6 },
];

Modify Sync Logic

Edit src/database/sync.ts:

• pullChanges() - How to fetch from server
• pushChanges() - How to send to server
• Conflict resolution strategy

---

7. Debugging Tips

Inspect Database

// In any component
import { useDatabase } from '@/hooks/useDatabase';

const { database } = useDatabase();
// database.collections.get('tasks').query().fetch().then(console.log)

Network Requests

• Use React Native Debugger
• Or flipper with react-native-flipper
• Enable console.log for sync operations

TypeScript Errors

# Full type check
npx tsc --noEmit

# Check specific file
npx tsc --noEmit src/components/TaskItem.tsx

---

8. Testing Checklist

Before Commit

• npx tsc --noEmit passes
• npx expo lint passes
• App runs on iOS simulator
• App runs on Android emulator
• App runs on web
• Offline mode works (disable network)
• Sync works (with mock server)

Manual Testing Flow

1. Add Task: Open app → FAB → Fill form → Submit → Verify in list
2. Category Filter: Tap categories → Verify filtering
3. Complete Task: Tap checkbox → Verify strikethrough + move to completed
4. Delete Task: Swipe left → Confirm → Verify removal
5. Subtasks: Add task with subtasks → Verify rendering
6. Calendar: Navigate to calendar → Select date → Verify tasks
7. Settings: Toggle dark mode → Verify persistence
8. Offline: Airplane mode → Add/edit tasks → Re-enable → Verify sync

---

9. Troubleshooting

Issue	Solution
npx expo start fails	rm -rf node_modules && npm install
Metro bundler issues	npx expo start -c
iOS build fails	cd ios && pod install && cd ..
Android build fails	cd android && ./gradlew clean && cd ..
TypeScript errors	Check tsconfig.json extends expo/tsconfig.base
Database not persisting	Verify expo-sqlite installed, check DatabaseProvider wraps app
Sync not working	Check API URL in .env, verify server running
Animations laggy	Enable useNativeDriver: true where possible

---

10. Useful Resources

• Expo Documentation
• WatermelonDB Docs
• React Hook Form
• Expo Router
• Reanimated 3
• TypeScript Handbook

---

11. Project Scripts (package.json)

{
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "lint": "expo lint",
    "typecheck": "tsc --noEmit",
    "format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
    "db:studio": "npx expo run:ios --configuration Debug",
    "build:ios": "eas build --platform ios",
    "build:android": "eas build --platform android",
    "build:web": "eas build --platform web",
    "submit:ios": "eas submit --platform ios",
    "submit:android": "eas submit --platform android"
  }
}