| name | expo-go |
| description | Manage Expo Go development workflow for React Native apps. Use when the user mentions Expo Go, starting development server, QR code scanning, testing on physical devices, network issues, running the app on mobile, Expo Router, file-based routing, navigation, tabs, deep linking, or URL schemes. |
| allowed-tools | Bash, Read, Grep, Glob, WebSearch |
Expo Go Development Skill
This skill helps manage Expo Go development workflow for React Native/Expo projects. Expo Go is a sandbox app for rapid mobile development without native build tools.
Note: This project uses bun as the default package manager. Use bunx instead of npx and bun run instead of npm run.
When to Use This Skill
- Starting development server for Expo Go
- Troubleshooting QR code or network issues
- Testing on physical iOS/Android devices
- Managing development environment
- Understanding Expo Go limitations
Quick Reference
Starting Development Server
bunx expo start
bunx expo start --tunnel
bunx expo start --clear
bunx expo start --port 8081
bunx expo start --lan
bunx expo start --localhost
bunx expo start --tunnel
Development Server Keyboard Shortcuts
When the dev server is running, use these keyboard shortcuts:
| Key | Action |
|---|
a | Open on Android device/emulator |
i | Open on iOS simulator (Mac only) |
w | Open in web browser |
r | Reload app |
m | Toggle menu |
j | Open debugger |
o | Open project code |
c | Show QR code |
? | Show all commands |
Connection Modes
LAN Mode (Default)
- Fastest performance
- Requires same Wi-Fi network
- Device and computer must be on same subnet
Tunnel Mode
- Works across networks
- Slower reload times
- Requires
@expo/ngrok (auto-installed)
- Use when: public Wi-Fi, VPN issues, firewall blocking
Local Mode
- Computer only (localhost)
- For emulator/simulator development
Expo Router
This project uses Expo Router for file-based routing. See EXPO-ROUTER.md for complete documentation.
Quick Reference
File Conventions:
| File | Purpose |
|---|
index.tsx | Default route for directory |
[param].tsx | Dynamic segment |
[...rest].tsx | Catch-all route |
_layout.tsx | Layout wrapper |
(group)/ | Route group (no URL segment) |
Navigation:
import { Link, useRouter } from 'expo-router'
<Link href="/settings">Settings</Link>
const router = useRouter()
router.push('/settings')
router.replace('/home')
router.back()
Reading Params:
import { useLocalSearchParams } from 'expo-router'
const { id } = useLocalSearchParams<{ id: string }>()
This Project's Structure:
app/
├── _layout.tsx # Root layout with TamaguiProvider
├── (tabs)/
│ ├── _layout.tsx # Tab navigator
│ ├── index.tsx # Home tab (/)
│ └── settings.tsx # Settings (/settings)
└── +not-found.tsx # 404 page
Deep Linking
URL Scheme Configuration
This project uses the scheme mattystack defined in app.json:
{
"expo": {
"scheme": "mattystack"
}
}
Link Formats by Platform
| Platform | Format |
|---|
| iOS/Android | mattystack://path |
| Web | https://yoursite.com/path |
| Expo Go | exp://192.168.x.x:8081/--/path |
Testing Deep Links
xcrun simctl openurl booted "mattystack://settings"
adb shell am start -W -a android.intent.action.VIEW -d "mattystack://settings"
Replit Development
This project is optimized for Replit development with special environment configuration.
Environment Variables
Use EXPO_PUBLIC_ prefix for client-accessible variables:
EXPO_PUBLIC_API_URL=https://api.example.com
EXPO_PUBLIC_ENV=development
Access in code:
const apiUrl = process.env.EXPO_PUBLIC_API_URL
Replit-Specific Commands
bun run expo:dev
Network Considerations
Replit runs in a container environment. Key considerations:
-
Use Tunnel Mode: LAN mode won't work from external devices
bunx expo start --tunnel
-
Webview URL: Access the web version via Replit's webview URL
-
Environment Variables: Set in Replit Secrets, not .env files in production
EAS Build vs Expo Go
When to Use Expo Go
- Rapid prototyping
- Testing expo-* packages
- No custom native code needed
- Learning and experimentation
When to Switch to Development Build
- Need custom native modules
- Using libraries that require native linking
- Push notifications
- In-app purchases
- Specific native configurations
Creating a Development Build
bun add -g eas-cli
eas build:configure
eas build --profile development --platform ios
eas build --profile development --platform android
Troubleshooting Guide
For detailed troubleshooting steps, see TROUBLESHOOTING.md.
Quick Fixes
QR Code Won't Scan:
- Use native camera app (not third-party scanner)
- Ensure good lighting
- Check Expo Go is installed and updated
"Network request failed" / Can't Connect:
- Verify same Wi-Fi network
- Try tunnel mode:
bunx expo start --tunnel
- Check firewall isn't blocking port 8081/19000
- Disable VPN temporarily
App Not Updating:
- Shake device → "Reload"
- Press
r in terminal
- Restart with
bunx expo start --clear
Expo Go Limitations
Expo Go is a sandbox environment with pre-bundled native modules. You cannot:
- Use custom native code
- Use libraries requiring native linking (e.g.,
react-native-firebase)
- Modify native iOS/Android configuration
- Use push notifications (requires development build)
- Use certain hardware features
Supported Libraries
All expo-* packages work in Expo Go. Check compatibility:
bunx expo install --check
For libraries requiring native code, you must switch to a development build.
Environment Variables
Set public environment variables in your app config:
{
"expo": {
"extra": {
"apiUrl": "https://api.example.com"
}
}
}
Or use .env files with EXPO_PUBLIC_ prefix:
EXPO_PUBLIC_API_URL=https://api.example.com
Access in code:
const apiUrl = process.env.EXPO_PUBLIC_API_URL;
Project-Specific Commands
This project uses bun as the package manager. Check package.json for:
bun run expo:dev
bunx expo start
Best Practices
- Keep Expo Go Updated: Outdated versions cause compatibility issues
- Use Same SDK Version: App SDK must match Expo Go version
- Clear Cache When Stuck:
bunx expo start --clear
- Prefer LAN Over Tunnel: Better performance when possible
- Check Network First: Most issues are network-related
SDK Compatibility
Current project SDK: Check app.json → expo.sdkVersion
Expo Go supports the latest SDK and one previous version. If your SDK is older, you must either:
- Upgrade SDK:
bunx expo install expo@latest
- Use a development build
Common Commands Reference
bunx expo --version
bunx expo login
bunx expo whoami
bunx expo install [package-name]
bunx expo doctor
bunx expo config
bunx expo start --clear
watchman watch-del-all
rm -rf node_modules/.cache
Device Setup
Android
- Install Expo Go from Google Play Store
- Enable Developer Options (tap Build Number 7 times)
- Enable USB Debugging (optional, for USB connection)
- Scan QR code with Expo Go app
iOS
- Install Expo Go from App Store
- Scan QR code with Camera app
- Tap the notification to open in Expo Go
Additional Resources