Skip to content

SETUP.md

Latest commit

 

History

History
303 lines (221 loc) · 5.82 KB

SETUP.md

File metadata and controls

303 lines (221 loc) · 5.82 KB

VibeBuilder Setup Guide

This guide will help you set up and run the VibeBuilder app on your development machine.

Prerequisites

Before you begin, ensure you have the following installed:

  1. Node.js (v18 or higher)

    node --version  # Should be 18.0.0 or higher

  2. npm or yarn

    npm --version  # Should be 8.0.0 or higher

  3. Expo CLI (optional but recommended)

    npm install -g expo-cli

  4. Development Environment

    • For iOS: Xcode (Mac only)
    • For Android: Android Studio with an emulator
    • For Web: Any modern browser

Step-by-Step Setup

1. Clone and Install

# Clone the repository
git clone <your-repo-url>
cd VibeBuilderApp

# Install dependencies
npm install

2. Environment Configuration

Create a .env file in the root directory:

cp .env.example .env

Edit .env and configure:

# Required for GitHub integration
EXPO_PUBLIC_GITHUB_ORG=your-organization-name
EXPO_PUBLIC_GITHUB_CLIENT_ID=your-github-oauth-client-id

3. GitHub OAuth Setup (Optional but Recommended)

To enable GitHub integration:

  1. Go to https://github.com/settings/developers
  2. Click "New OAuth App"
  3. Fill in the details:
    • Application name: VibeBuilder
    • Homepage URL: http://localhost:8081
    • Authorization callback URL: exp://localhost:19000/--/auth/callback
  4. Copy the Client ID to your .env file
  5. Keep the Client Secret secure (will need a backend for production)

4. Start the Development Server

npm start

This will start the Expo development server. You'll see a QR code in the terminal.

5. Run on Your Platform

Choose your platform:

iOS (Mac only)

npm run ios
# or press 'i' in the terminal

Android

npm run android
# or press 'a' in the terminal

Web

npm run web
# or press 'w' in the terminal

Physical Device

  1. Install Expo Go app from App Store or Google Play
  2. Scan the QR code shown in the terminal
  3. The app will load on your device

Troubleshooting

Common Issues

1. Metro Bundler Port Already in Use

# Kill the process using port 8081
npx react-native start --reset-cache

2. iOS Simulator Issues

# Reset iOS simulator
xcrun simctl erase all

# Rebuild
npm run ios

3. Android Emulator Issues

# Clean and rebuild
cd android
./gradlew clean
cd ..
npm run android

4. Dependencies Issues

# Clear cache and reinstall
rm -rf node_modules
rm package-lock.json
npm install

5. TypeScript Errors

# Run type checking
npm run type-check

# Some errors can be fixed by restarting TypeScript server in your IDE

Error Messages

"Unable to resolve module"

  • Solution: Clear Metro cache with npx expo start -c

"GitHub not connected"

  • Solution: Set up GitHub OAuth and connect in Settings

"Template not found"

  • Solution: Ensure templates are loaded by checking the app store

Development Workflow

1. File Structure

  • Put new components in /src/components/
  • Add new screens in /src/screens/
  • Create services in /src/services/
  • Add types in /src/types/

2. State Management

  • Use Zustand stores in /src/store/
  • Access with hooks: useAuthStore(), useAppStore(), useUIStore()

3. Theme System

  • Access theme with useTheme() hook
  • Colors, spacing, typography defined in /src/constants/

4. Navigation

  • Routes defined in /src/types/index.ts
  • Navigator in /src/navigation/AppNavigator.tsx

Testing Your Changes

Manual Testing

  1. Authentication Flow

    • Register a new account
    • Logout and login
    • Check data persistence

  2. App Creation

    • Generate an app from prompt
    • Check preview rendering
    • Verify app saved in My Apps

  3. Template System

    • Browse templates
    • Use a template
    • Customize a template

  4. Theme Toggle

    • Switch between light/dark/system
    • Verify colors update correctly

Validation

# Type checking
npm run type-check

# Linting
npm run lint

# Format code
npm run format

Building for Production

Development Build

# Configure EAS
eas build:configure

# Build for iOS
eas build --profile development --platform ios

# Build for Android
eas build --profile development --platform android

Production Build

# iOS
eas build --profile production --platform ios

# Android
eas build --profile production --platform android

Next Steps

  1. Customize Templates: Edit /src/services/api/templateData.ts
  2. Integrate Real AI: Replace mock service in /src/services/ai/aiService.ts
  3. Add Backend: Set up authentication and data persistence
  4. Implement Analytics: Add tracking for user behavior
  5. Add Tests: Write unit and integration tests

Getting Help

If you encounter issues:

  1. Check this guide and README.md
  2. Review error messages carefully
  3. Check Expo documentation: https://docs.expo.dev/
  4. Search GitHub issues
  5. Ask for help in discussions

Useful Commands

# Start with cache clear
npm start -- --clear

# Type checking
npm run type-check

# Linting
npm run lint

# Format all files
npm run format

# Update dependencies
npm update

# Check for outdated packages
npm outdated

# Clean install
rm -rf node_modules && npm install

Development Tips

  1. Hot Reloading: Changes auto-reload in dev mode
  2. Fast Refresh: Preserves component state between updates
  3. Debug Menu: Shake device or press Cmd+D (iOS) / Cmd+M (Android)
  4. Element Inspector: Tap with 3 fingers (device) or Cmd+D > Inspector
  5. Performance Monitor: Enable in Debug Menu

Environment Variables

Remember to never commit:

  • .env file (contains secrets)
  • API keys
  • OAuth secrets
  • Personal tokens

Always use .env.example as a template.

Happy building! 🚀