Quick Start

Get PokéDex Fleek running on your device in 5 minutes

This guide will help you set up and run PokéDex Fleek on your Android or iOS device. The app requires a physical device since camera features don’t work in simulators.

Prerequisites

Before you begin, make sure you have:

Node.js and npm

Install Node.js 18 or later from nodejs.org. This includes npm automatically.

Verify installation:

Terminal

node --version
npm --version

Expo CLI

Install Expo CLI globally:

Terminal

npm install -g expo-cli

Physical Device

Important: You need a physical Android or iOS device. The app will not work in:

• Expo Go app (native modules required)
• Android emulators (camera issues)
• iOS Simulator (no camera support)

You’ll need:

• USB cable for device connection
• Developer mode enabled on your device

Setup Steps

1. Clone the repository

   Clone the project from GitHub and navigate to the directory:

   Terminal

   git clone https://github.com/soymatudev/Pokedex-Fleek.git
   cd Pokedex-Fleek
   
2. Install dependencies

   Install all required npm packages:

   npm

   npm install
   

   This installs key dependencies including:

   • react-native-vision-camera for camera access
   • expo-speech for voice narration
   • react-native-image-colors for color extraction
   • @react-navigation/native for navigation
3. Generate native code

   Run Expo prebuild to generate native Android/iOS projects:

   Terminal

   npx expo prebuild
   

   This creates:

   • android/ directory for Android native code
   • ios/ directory for iOS native code

   You only need to run this once, unless you modify native dependencies in package.json or app.json.

4. Run on your device

   Connect your device via USB and run the appropriate command:

   Android

   Enable USB debugging on your Android device, then:

   Terminal

   npx expo run:android
   

   The app will:

   1. Build the Android APK
   2. Install it on your connected device
   3. Launch the app automatically

   iOS

   Connect your iPhone and ensure it’s trusted, then:

   Terminal

   npx expo run:ios --device
   

   iOS requires a Mac with Xcode installed. The first build can take 10-15 minutes.

5. Grant camera permissions

   When the app launches for the first time:

   1. You’ll see a permission dialog asking for camera access
   2. Tap Allow or While Using the App
   3. The app needs camera access to scan and analyze objects

   If you accidentally denied permissions:

   • Android: Go to Settings → Apps → Pokedex Fleek → Permissions → Camera → Allow
   • iOS: Go to Settings → Privacy → Camera → Pokedex Fleek → Enable
6. Scan your first Pokémon

   Now you’re ready to identify your first Pokémon!

   1. From the home screen, tap “Escáner de Campo” (Field Scanner)
   2. Point your camera at any colorful object
   3. Tap the Pokéball button at the bottom
   4. Wait for the color analysis (1-2 seconds)
   5. View the matched Pokémon with stats and voice narration

   How the matching works

   The app captures a photo, extracts the dominant color using react-native-image-colors, converts it to HSL hue (0-360°), and finds the Pokémon with the closest matching color range.

   For example:

   • Red objects (0-30° hue) → Charmander, Flareon, Charmeleon
   • Blue objects (180-240° hue) → Squirtle, Lapras, Vaporeon
   • Yellow objects (40-70° hue) → Pikachu, Zapdos, Jolteon

Your First Scan

Here’s what happens when you scan an object:

1. Capture: The camera takes a photo when you tap the Pokéball button
2. Extract: react-native-image-colors finds the dominant color (platform-specific algorithm)
3. Convert: The hexToHue() function converts the hex color to hue (0-360°)
4. Match: The app searches POKEMON_DB for Pokémon with matching color ranges
5. Display: Navigate to the details screen showing the matched Pokémon
6. Narrate: Dexter voice reads the Pokédex entry in Spanish using expo-speech

The color matching uses hue-based ranges rather than Euclidean distance in this implementation. Each Pokémon is mapped to a specific hue range (e.g., Bulbasaur: 90-150° for green).

Troubleshooting

Camera permission denied

If you see “Dexter necesita permisos de cámara”:

Android:

1. Open device Settings
2. Go to Apps → Pokedex Fleek → Permissions
3. Enable Camera permission
4. Restart the app

iOS:

1. Open device Settings
2. Go to Privacy → Camera
3. Enable Pokedex Fleek
4. Restart the app

Expo Go not supported

You may see an error like “Invariant Violation: TurboModuleRegistry.getEnforcing(…) VisionCameraProxy”

Solution: You cannot use Expo Go for this app. You must build a development build:

npx expo prebuild
npx expo run:android  # or run:ios

Development builds include native modules like react-native-vision-camera.

Android build fails

Common Android build errors:

Gradle build failed:

• Clear Gradle cache: cd android && ./gradlew clean
• Update Android SDK: Open Android Studio → SDK Manager → Update

ADB device not found:

• Enable USB debugging: Settings → Developer Options → USB Debugging
• Run adb devices to verify connection
• Try a different USB cable (some are charge-only)

iOS build fails

Common iOS build errors:

Code signing error:

• Open ios/PokedexFleek.xcworkspace in Xcode
• Select your development team in Signing & Capabilities
• Change bundle identifier if needed

CocoaPods issues:

Terminal

cd ios
pod deintegrate
pod install
cd ..
npx expo run:ios --device

Black camera screen

If the camera view is black:

1. Check permissions: Verify camera access in device settings
2. Restart app: Close and reopen the app completely
3. Rebuild: Sometimes native changes need a rebuild
   npx expo prebuild --clean
   npx expo run:android  # or run:ios
   
4. Check device: Test camera with native camera app to ensure hardware works

Next Steps

Now that you have the app running, explore more:

Detailed Installation

Platform-specific setup guides for Android Studio and Xcode

Understanding the Tech

Learn about the feature-based architecture and data flow

Camera Scanner

Deep dive into how the camera scanning and color extraction works

Development Guide

Set up your local development environment and debugging tools