This skill provides expert knowledge on Expo project configuration, environment management, and the `expo` CLI.
/plugin marketplace add rahulkeerthi/expo-toolkit/plugin install expo-toolkit@withqwertyThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides expert knowledge on Expo project configuration, environment management, and the expo CLI.
app.config.js (dynamic configuration)expo doctor for project health checksUse app.config.js (recommended):
Use app.json:
If you have an existing app.json:
// app.config.js
export default ({ config }) => {
return {
...config,
// Your customizations here
};
};
Or start fresh:
// app.config.js
export default {
name: "My App",
slug: "my-app",
// ... rest of config
};
The recommended pattern for running dev/preview/production builds side-by-side on the same device:
// app.config.js
const IS_DEV = process.env.APP_VARIANT === 'development';
const IS_PREVIEW = process.env.APP_VARIANT === 'preview';
const getUniqueIdentifier = () => {
if (IS_DEV) {
return 'com.yourcompany.yourapp.dev';
}
if (IS_PREVIEW) {
return 'com.yourcompany.yourapp.preview';
}
return 'com.yourcompany.yourapp';
};
const getAppName = () => {
if (IS_DEV) {
return 'YourApp (Dev)';
}
if (IS_PREVIEW) {
return 'YourApp (Preview)';
}
return 'YourApp';
};
export default {
name: getAppName(),
slug: 'your-app',
version: '1.0.0',
orientation: 'portrait',
icon: './assets/icon.png',
userInterfaceStyle: 'automatic',
splash: {
image: './assets/splash.png',
resizeMode: 'contain',
backgroundColor: '#ffffff',
},
assetBundlePatterns: ['**/*'],
ios: {
supportsTablet: true,
bundleIdentifier: getUniqueIdentifier(),
},
android: {
adaptiveIcon: {
foregroundImage: './assets/adaptive-icon.png',
backgroundColor: '#ffffff',
},
package: getUniqueIdentifier(),
},
web: {
favicon: './assets/favicon.png',
},
extra: {
eas: {
projectId: 'your-project-id',
},
},
};
{
"build": {
"development": {
"developmentClient": true,
"distribution": "internal",
"env": {
"APP_VARIANT": "development"
}
},
"preview": {
"distribution": "internal",
"env": {
"APP_VARIANT": "preview"
}
},
"production": {
"env": {
"APP_VARIANT": "production"
}
}
}
}
| Type | Prefix | Available | Use Case |
|---|---|---|---|
| Build-time | None | app.config.js only | Bundle ID, app name |
| Runtime | EXPO_PUBLIC_ | App code | API URLs, feature flags |
Used in app.config.js during build:
// app.config.js
const API_URL = process.env.API_URL || 'https://api.default.com';
export default {
// ...
extra: {
apiUrl: API_URL,
},
};
Set in eas.json:
{
"build": {
"production": {
"env": {
"API_URL": "https://api.production.com"
}
}
}
}
Variables accessible in your app code:
// In eas.json
{
"build": {
"production": {
"env": {
"EXPO_PUBLIC_API_URL": "https://api.example.com"
}
}
}
}
// In your app code
const apiUrl = process.env.EXPO_PUBLIC_API_URL;
IMPORTANT: EXPO_PUBLIC_ variables are embedded in the JS bundle. Never use for secrets!
For local development, use .env files:
# .env.local (gitignored)
EXPO_PUBLIC_API_URL=http://localhost:3000
Install expo-env:
npx expo install expo-env
Run diagnostics to check project health:
npx expo doctor
| Issue | Solution |
|---|---|
| SDK version mismatch | Update packages: npx expo install --fix |
| Deprecated packages | Migrate to recommended alternatives |
| Invalid config | Fix app.config.js / app.json |
| Missing peer dependencies | Install missing packages |
| Native module issues | Run npx expo prebuild --clean |
# Fix package version mismatches
npx expo install --fix
# Clear caches and reinstall
rm -rf node_modules
rm -rf .expo
npm install
# Regenerate native projects (if using prebuild)
npx expo prebuild --clean
// app.config.js
const IS_DEV = process.env.APP_VARIANT === 'development';
const IS_PREVIEW = process.env.APP_VARIANT === 'preview';
const getUniqueIdentifier = () => {
if (IS_DEV) return 'com.yourcompany.yourapp.dev';
if (IS_PREVIEW) return 'com.yourcompany.yourapp.preview';
return 'com.yourcompany.yourapp';
};
const getAppName = () => {
if (IS_DEV) return 'YourApp (Dev)';
if (IS_PREVIEW) return 'YourApp (Preview)';
return 'YourApp';
};
export default {
// Basic Info
name: getAppName(),
slug: 'your-app',
version: '1.0.0',
orientation: 'portrait',
// Assets
icon: './assets/icon.png',
splash: {
image: './assets/splash.png',
resizeMode: 'contain',
backgroundColor: '#ffffff',
},
assetBundlePatterns: ['**/*'],
// Appearance
userInterfaceStyle: 'automatic',
// iOS Configuration
ios: {
supportsTablet: false, // or true for iPad support
bundleIdentifier: getUniqueIdentifier(),
buildNumber: '1',
infoPlist: {
NSCameraUsageDescription: 'This app uses the camera to...',
NSPhotoLibraryUsageDescription: 'This app accesses photos to...',
// Add other permissions as needed
},
config: {
usesNonExemptEncryption: false, // If no custom encryption
},
},
// Android Configuration
android: {
package: getUniqueIdentifier(),
versionCode: 1,
adaptiveIcon: {
foregroundImage: './assets/adaptive-icon.png',
backgroundColor: '#ffffff',
},
permissions: [
// Add permissions as needed
// 'android.permission.CAMERA',
// 'android.permission.READ_EXTERNAL_STORAGE',
],
},
// Web Configuration (if applicable)
web: {
favicon: './assets/favicon.png',
bundler: 'metro',
},
// Plugins
plugins: [
// Add Expo plugins here
// 'expo-camera',
// ['expo-image-picker', { photosPermission: '...' }],
],
// Extra Configuration
extra: {
eas: {
projectId: 'your-eas-project-id',
},
// Add custom config accessible via expo-constants
},
// Updates (EAS Update)
updates: {
url: 'https://u.expo.dev/your-project-id',
},
runtimeVersion: {
policy: 'appVersion',
},
// Owner (for EAS)
owner: 'your-expo-username',
};
| Field | Description | Example |
|---|---|---|
name | Display name | "My App" |
slug | URL-friendly name | "my-app" |
version | User-facing version | "1.0.0" |
ios.bundleIdentifier | iOS bundle ID | "com.company.app" |
android.package | Android package name | "com.company.app" |
| Field | Platform | Description |
|---|---|---|
version | Both | Semantic version shown to users |
ios.buildNumber | iOS | Internal build number (string) |
android.versionCode | Android | Internal version code (integer) |
Tip: Use autoIncrement in EAS to manage build numbers automatically.
| Field | Size | Format |
|---|---|---|
icon | 1024x1024 | PNG |
splash.image | 1284x2778 (or similar) | PNG |
android.adaptiveIcon.foregroundImage | 1024x1024 | PNG |
web.favicon | 48x48 | PNG |
Add to ios.infoPlist:
infoPlist: {
NSCameraUsageDescription: 'Required for taking photos',
NSPhotoLibraryUsageDescription: 'Required for selecting photos',
NSLocationWhenInUseUsageDescription: 'Required for location features',
NSMicrophoneUsageDescription: 'Required for recording audio',
NSFaceIDUsageDescription: 'Required for secure authentication',
}
Add to android.permissions:
permissions: [
'android.permission.CAMERA',
'android.permission.READ_EXTERNAL_STORAGE',
'android.permission.WRITE_EXTERNAL_STORAGE',
'android.permission.ACCESS_FINE_LOCATION',
'android.permission.RECORD_AUDIO',
]
For native configuration that goes beyond standard options:
plugins: [
// Simple plugin
'expo-camera',
// Plugin with options
['expo-image-picker', {
photosPermission: 'Allow access to select photos',
}],
// Custom plugin (local)
'./plugins/my-plugin.js',
]
| Plugin | Purpose |
|---|---|
expo-camera | Camera access |
expo-image-picker | Photo library access |
expo-notifications | Push notifications |
expo-location | Location services |
expo-av | Audio/video playback |
expo-build-properties | Native build settings |
For over-the-air updates:
export default {
// ...
updates: {
url: 'https://u.expo.dev/your-project-id',
fallbackToCacheTimeout: 0,
},
runtimeVersion: {
policy: 'appVersion', // or 'sdkVersion', 'fingerprint', or explicit version
},
};
| Policy | When Updates Apply |
|---|---|
appVersion | Same version in config |
sdkVersion | Same Expo SDK version |
fingerprint | Same native code fingerprint |
"1.0.0" | Explicit version string |
# Clear Metro cache
npx expo start --clear
# Clear all caches
rm -rf node_modules/.cache
rm -rf .expo
eas.json for the correct profileEXPO_PUBLIC_ prefixIf you get "app already installed" errors when switching environments:
APP_VARIANT is set correctly in build profile# Start development server
npx expo start
# Start with clean cache
npx expo start --clear
# Run diagnostics
npx expo doctor
# Fix package versions
npx expo install --fix
# Install a package
npx expo install package-name
# Generate native projects
npx expo prebuild
# Clean and regenerate native projects
npx expo prebuild --clean
# Export for web
npx expo export --platform web
# View config
npx expo config
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.