258 lines
6.4 KiB
Markdown
258 lines
6.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
npx expo start
|
|
```
|
|
|
|
### Terminal 2: Run on Platform
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
```typescript
|
|
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
|
|
```typescript
|
|
// 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
|
|
```bash
|
|
# 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](https://docs.expo.dev/)
|
|
- [WatermelonDB Docs](https://nozbe.github.io/WatermelonDB/)
|
|
- [React Hook Form](https://react-hook-form.com/)
|
|
- [Expo Router](https://expo.github.io/router/)
|
|
- [Reanimated 3](https://docs.swmansion.com/react-native-reanimated/)
|
|
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
|
|
|
|
---
|
|
|
|
## 11. Project Scripts (package.json)
|
|
|
|
```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"
|
|
}
|
|
}
|
|
``` |