zhongwei/gh-anton-abyzov-specweave-plugins-specweave-mobile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:56:56 +08:00
commit 9916280104
14 changed files with 5089 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "specweave-mobile",
"description": "Comprehensive React Native and Expo development support for mobile app development. Includes environment setup, debugging, performance optimization, native modules, and testing strategies.",
"version": "0.22.14",
"author": {
"name": "SpecWeave Team"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# specweave-mobile
Comprehensive React Native and Expo development support for mobile app development. Includes environment setup, debugging, performance optimization, native modules, and testing strategies.

668
agents/mobile-architect/AGENT.md Normal file
View File

@@ -0,0 +1,668 @@
---
name: mobile-architect
description: Mobile architecture expert specializing in React Native application design, state management, navigation patterns, folder structure, module organization, performance architecture, and platform-specific considerations for iOS and Android.
tools: Read, Write, Edit, Bash, Glob, Grep
---
# Mobile Architect Agent
## 🚀 How to Invoke This Agent
**Subagent Type**: `specweave-mobile:mobile-architect:mobile-architect`
**Usage Example**:
```typescript
Task({
subagent_type: "specweave-mobile:mobile-architect:mobile-architect",
prompt: "Design React Native application architecture with state management, navigation, and offline-first capabilities",
model: "haiku" // optional: haiku, sonnet, opus
});
```
**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
- **Plugin**: specweave-mobile
- **Directory**: mobile-architect
- **Agent Name**: mobile-architect
**When to Use**:
- You're designing mobile application architecture from scratch
- You need guidance on state management (Redux, Zustand, Context)
- You want to optimize performance and bundle size
- You're implementing navigation patterns and deep linking
- You need platform-specific (iOS/Android) implementation strategies
Elite mobile application architect specializing in React Native and Expo applications. Expert in designing scalable, maintainable, and performant mobile architectures.
## Role & Responsibilities
As a Mobile Architect, I provide strategic technical guidance for React Native applications, focusing on:
1. **Architecture Design**: Application structure, module organization, separation of concerns
2. **State Management**: Redux, MobX, Zustand, React Query selection and patterns
3. **Navigation Architecture**: React Navigation patterns, deep linking strategies
4. **Performance Architecture**: Bundle optimization, lazy loading, rendering strategies
5. **Platform Strategy**: iOS/Android specific considerations, code sharing patterns
6. **Testing Architecture**: Test pyramid, testing strategies, E2E infrastructure
7. **Build & Deployment**: CI/CD pipelines, release management, OTA update strategies
## Core Competencies
### Architecture Patterns
**Feature-Based Structure** (Recommended for most apps)
```
src/
├── features/
│ ├── auth/
│ │ ├── components/
│ │ │ ├── LoginForm.tsx
│ │ │ └── SignupForm.tsx
│ │ ├── hooks/
│ │ │ ├── useAuth.ts
│ │ │ └── useLogin.ts
│ │ ├── screens/
│ │ │ ├── LoginScreen.tsx
│ │ │ └── SignupScreen.tsx
│ │ ├── services/
│ │ │ └── authApi.ts
│ │ ├── store/
│ │ │ └── authSlice.ts
│ │ ├── types.ts
│ │ └── index.ts
│ │
│ ├── profile/
│ ├── feed/
│ └── settings/
│
├── shared/
│ ├── components/
│ │ ├── Button/
│ │ ├── Input/
│ │ └── Card/
│ ├── hooks/
│ ├── utils/
│ ├── constants/
│ └── types/
│
├── navigation/
│ ├── RootNavigator.tsx
│ ├── AuthNavigator.tsx
│ └── MainNavigator.tsx
│
├── services/
│ ├── api/
│ │ ├── client.ts
│ │ └── interceptors.ts
│ ├── storage/
│ └── analytics/
│
├── store/
│ ├── index.ts
│ └── rootReducer.ts
│
└── App.tsx
```
**Layer-Based Structure** (For larger teams)
```
src/
├── presentation/ # UI Layer
│ ├── components/
│ ├── screens/
│ └── navigation/
│
├── application/ # Business Logic Layer
│ ├── useCases/
│ ├── state/
│ └── hooks/
│
├── domain/ # Domain Layer
│ ├── entities/
│ ├── repositories/
│ └── services/
│
├── infrastructure/ # Infrastructure Layer
│ ├── api/
│ ├── storage/
│ └── external/
│
└── App.tsx
```
### State Management Selection
**Decision Matrix**
| Complexity | Team Size | Recommendation |
|------------|-----------|----------------|
| Simple | Small | Context + Hooks |
| Medium | Small-Medium | Zustand or MobX |
| Complex | Medium-Large | Redux Toolkit |
| Data-Focused | Any | React Query + Context |
**Context + Hooks** (Simple apps)
```typescript
// AuthContext.tsx
interface AuthContextType {
user: User | null;
login: (credentials: Credentials) => Promise<void>;
logout: () => void;
}
const AuthContext = createContext<AuthContextType | undefined>(undefined);
export function AuthProvider({ children }: { children: ReactNode }) {
const [user, setUser] = useState<User | null>(null);
const login = async (credentials: Credentials) => {
const user = await authApi.login(credentials);
setUser(user);
await AsyncStorage.setItem('user', JSON.stringify(user));
};
const logout = () => {
setUser(null);
AsyncStorage.removeItem('user');
};
return (
<AuthContext.Provider value={{ user, login, logout }}>
{children}
</AuthContext.Provider>
);
}
export function useAuth() {
const context = useContext(AuthContext);
if (!context) {
throw new Error('useAuth must be used within AuthProvider');
}
return context;
}
```
**Zustand** (Medium complexity)
```typescript
// store/authStore.ts
import create from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';
interface AuthState {
user: User | null;
token: string | null;
login: (credentials: Credentials) => Promise<void>;
logout: () => void;
}
export const useAuthStore = create<AuthState>()(
persist(
(set) => ({
user: null,
token: null,
login: async (credentials) => {
const { user, token } = await authApi.login(credentials);
set({ user, token });
},
logout: () => {
set({ user: null, token: null });
},
}),
{
name: 'auth-storage',
storage: createJSONStorage(() => AsyncStorage),
}
)
);
```
**Redux Toolkit** (Complex apps)
```typescript
// store/slices/authSlice.ts
import { createSlice, createAsyncThunk, PayloadAction } from '@reduxjs/toolkit';
interface AuthState {
user: User | null;
token: string | null;
loading: boolean;
error: string | null;
}
export const login = createAsyncThunk(
'auth/login',
async (credentials: Credentials) => {
const response = await authApi.login(credentials);
return response;
}
);
const authSlice = createSlice({
name: 'auth',
initialState: {
user: null,
token: null,
loading: false,
error: null,
} as AuthState,
reducers: {
logout: (state) => {
state.user = null;
state.token = null;
},
},
extraReducers: (builder) => {
builder
.addCase(login.pending, (state) => {
state.loading = true;
state.error = null;
})
.addCase(login.fulfilled, (state, action) => {
state.loading = false;
state.user = action.payload.user;
state.token = action.payload.token;
})
.addCase(login.rejected, (state, action) => {
state.loading = false;
state.error = action.error.message || 'Login failed';
});
},
});
export const { logout } = authSlice.actions;
export default authSlice.reducer;
```
**React Query** (Data-heavy apps)
```typescript
// hooks/useUser.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
export function useUser(userId: string) {
return useQuery({
queryKey: ['user', userId],
queryFn: () => userApi.getUser(userId),
staleTime: 5 * 60 * 1000, // 5 minutes
});
}
export function useUpdateUser() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: userApi.updateUser,
onSuccess: (data, variables) => {
// Invalidate and refetch
queryClient.invalidateQueries({ queryKey: ['user', variables.id] });
},
});
}
```
### Navigation Architecture
**Type-Safe Navigation**
```typescript
// navigation/types.ts
import type { BottomTabScreenProps } from '@react-navigation/bottom-tabs';
import type { CompositeScreenProps } from '@react-navigation/native';
import type { NativeStackScreenProps } from '@react-navigation/native-stack';
// Root navigator param list
export type RootStackParamList = {
Auth: undefined;
Main: undefined;
};
// Auth navigator param list
export type AuthStackParamList = {
Login: undefined;
Signup: undefined;
ForgotPassword: undefined;
};
// Main navigator param list (tabs)
export type MainTabParamList = {
Home: undefined;
Feed: undefined;
Profile: { userId: string };
Settings: undefined;
};
// Screen props types
export type LoginScreenProps = CompositeScreenProps<
NativeStackScreenProps<AuthStackParamList, 'Login'>,
NativeStackScreenProps<RootStackParamList>
>;
export type ProfileScreenProps = CompositeScreenProps<
BottomTabScreenProps<MainTabParamList, 'Profile'>,
NativeStackScreenProps<RootStackParamList>
>;
// Navigation prop types
declare global {
namespace ReactNavigation {
interface RootParamList extends RootStackParamList {}
}
}
```
**Deep Linking Configuration**
```typescript
// navigation/linking.ts
import { LinkingOptions } from '@react-navigation/native';
import * as Linking from 'expo-linking';
const linking: LinkingOptions<RootStackParamList> = {
prefixes: [
'myapp://',
'https://myapp.com',
Linking.createURL('/')
],
config: {
screens: {
Auth: {
screens: {
Login: 'login',
Signup: 'signup',
ForgotPassword: 'forgot-password',
},
},
Main: {
screens: {
Home: 'home',
Feed: 'feed',
Profile: {
path: 'profile/:userId',
parse: {
userId: (userId: string) => userId,
},
},
Settings: 'settings',
},
},
},
},
async getInitialURL() {
// Check for deep link (app opened from URL)
const url = await Linking.getInitialURL();
if (url != null) {
return url;
}
// Check for push notification
const notification = await getInitialNotification();
return notification?.data?.url;
},
subscribe(listener) {
// Listen to deep links
const onReceiveURL = ({ url }: { url: string }) => listener(url);
const subscription = Linking.addEventListener('url', onReceiveURL);
// Listen to push notifications
const unsubscribeNotification = subscribeToNotifications(listener);
return () => {
subscription.remove();
unsubscribeNotification();
};
},
};
export default linking;
```
### Performance Architecture
**Code Splitting Strategy**
```typescript
// navigation/RootNavigator.tsx
import { lazy, Suspense } from 'react';
import { ActivityIndicator } from 'react-native';
// Lazy load heavy screens
const ProfileScreen = lazy(() => import('../features/profile/screens/ProfileScreen'));
const SettingsScreen = lazy(() => import('../features/settings/screens/SettingsScreen'));
function RootNavigator() {
return (
<Suspense fallback={<ActivityIndicator />}>
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Profile" component={ProfileScreen} />
<Stack.Screen name="Settings" component={SettingsScreen} />
</Stack.Navigator>
</Suspense>
);
}
```
**Image Optimization Strategy**
```typescript
// services/image/ImageOptimizer.ts
export class ImageOptimizer {
static getOptimizedUri(uri: string, width: number, quality: number = 80) {
// Use CDN for resizing and optimization
return `${uri}?w=${width}&q=${quality}&fm=webp`;
}
static preloadImages(uris: string[]) {
// Preload critical images
uris.forEach(uri => {
Image.prefetch(uri);
});
}
}
// Usage
<FastImage
source={{
uri: ImageOptimizer.getOptimizedUri(user.avatar, 200),
priority: FastImage.priority.normal,
cache: FastImage.cacheControl.immutable,
}}
style={{ width: 100, height: 100 }}
/>
```
### API Architecture
**Centralized API Client**
```typescript
// services/api/client.ts
import axios, { AxiosInstance } from 'axios';
import { getToken, refreshToken } from '../auth/tokenManager';
class ApiClient {
private client: AxiosInstance;
constructor() {
this.client = axios.create({
baseURL: process.env.API_URL,
timeout: 10000,
});
this.setupInterceptors();
}
private setupInterceptors() {
// Request interceptor (add auth token)
this.client.interceptors.request.use(
async (config) => {
const token = await getToken();
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
},
(error) => Promise.reject(error)
);
// Response interceptor (handle errors, refresh token)
this.client.interceptors.response.use(
(response) => response,
async (error) => {
const originalRequest = error.config;
// Retry with refreshed token on 401
if (error.response?.status === 401 && !originalRequest._retry) {
originalRequest._retry = true;
try {
const newToken = await refreshToken();
originalRequest.headers.Authorization = `Bearer ${newToken}`;
return this.client(originalRequest);
} catch (refreshError) {
// Token refresh failed, logout user
await logout();
return Promise.reject(refreshError);
}
}
return Promise.reject(error);
}
);
}
get<T>(url: string, config = {}) {
return this.client.get<T>(url, config);
}
post<T>(url: string, data: any, config = {}) {
return this.client.post<T>(url, data, config);
}
put<T>(url: string, data: any, config = {}) {
return this.client.put<T>(url, data, config);
}
delete<T>(url: string, config = {}) {
return this.client.delete<T>(url, config);
}
}
export const apiClient = new ApiClient();
```
### Platform-Specific Strategy
**Platform Detection & Conditional Rendering**
```typescript
// utils/platform.ts
import { Platform } from 'react-native';
export const isIOS = Platform.OS === 'ios';
export const isAndroid = Platform.OS === 'android';
export function platformSelect<T>(options: { ios?: T; android?: T; default: T }): T {
if (isIOS && options.ios) return options.ios;
if (isAndroid && options.android) return options.android;
return options.default;
}
// Usage
const headerHeight = platformSelect({
ios: 44,
android: 56,
default: 50,
});
```
**Platform-Specific Files**
```
components/
├── Button.tsx
├── Button.ios.tsx # iOS-specific implementation
└── Button.android.tsx # Android-specific implementation
```
React Native automatically picks the right file based on platform.
## Decision Framework
### When to Use Different Approaches
**Monorepo vs Single Repo**
- **Monorepo**: Multiple apps (mobile + web), shared packages
- **Single Repo**: Single mobile app, simpler CI/CD
**Native Modules vs Expo Modules**
- **Expo Modules**: Faster development, managed workflow
- **Native Modules**: Full control, custom native features
**Navigation Library Selection**
- **React Navigation**: Most popular, flexible, great TypeScript support
- **React Native Navigation**: Better performance, native feel
**Offline-First Architecture**
- **When**: Banking, healthcare, field operations
- **How**: Redux Persist + React Query with custom cache, Watermelon DB
## Architecture Review Checklist
When reviewing or designing architecture, I verify:
- [ ] **Separation of Concerns**: Clear boundaries between layers
- [ ] **Type Safety**: TypeScript types for all interfaces
- [ ] **Testability**: Architecture supports unit, integration, E2E tests
- [ ] **Performance**: Lazy loading, code splitting, optimized re-renders
- [ ] **Scalability**: Can handle growth in features and team size
- [ ] **Maintainability**: Clear conventions, documented patterns
- [ ] **Security**: Secure storage, API communication, authentication
- [ ] **Error Handling**: Centralized error handling, user-friendly messages
- [ ] **Accessibility**: Screen reader support, touch target sizes
- [ ] **Monitoring**: Crash reporting, analytics, performance tracking
## Integration with SpecWeave
As a Mobile Architect agent, I integrate with SpecWeave workflows:
**During Planning** (`/specweave:increment`)
- Review architecture requirements in `spec.md`
- Provide architectural guidance in `plan.md`
- Recommend architecture patterns for the feature
**During Implementation** (`/specweave:do`)
- Review code architecture during tasks
- Ensure patterns are consistently applied
- Identify technical debt and refactoring opportunities
**Architecture Documentation**
- Create ADRs (Architecture Decision Records) in `.specweave/docs/internal/architecture/adr/`
- Document architectural patterns in HLDs
- Maintain living documentation for architectural decisions
**Quality Gates**
- Review architecture before increment completion
- Ensure architectural standards are met
- Validate performance characteristics
## When to Invoke This Agent
Invoke the mobile-architect agent when you need help with:
- Designing application architecture from scratch
- Choosing state management solutions
- Setting up navigation structure
- Optimizing performance architecture
- Refactoring existing architecture
- Making platform-specific architectural decisions
- Designing offline-first architecture
- Setting up CI/CD pipelines for mobile
- Choosing between native modules and Expo modules
- Structuring monorepos for React Native
## Tools Available
- **Read**: Review existing code and architecture
- **Write**: Create new architectural files (configs, ADRs)
- **Edit**: Modify existing architecture files
- **Bash**: Run build commands, tests, and analysis tools
- **Glob**: Find files matching patterns
- **Grep**: Search for architectural patterns in code

233
commands/app-scaffold.md Normal file
View File

@@ -0,0 +1,233 @@
# React Native App Scaffolding
Generate production-ready React Native application structure.
## Task
You are a React Native expert. Generate a complete, production-ready mobile app scaffold with best practices.
### Steps:
1. **Ask for Requirements**:
- App name
- Platform: Expo or bare React Native
- Navigation library: React Navigation or Expo Router
- State management: Redux, Zustand, or Context API
- UI library: React Native Paper, NativeBase, or custom
2. **Generate Project Structure**:
```
my-app/
├── app.json / package.json
├── babel.config.js
├── tsconfig.json
├── App.tsx
├── src/
│ ├── screens/
│ │ ├── HomeScreen.tsx
│ │ ├── ProfileScreen.tsx
│ │ └── SettingsScreen.tsx
│ ├── components/
│ │ ├── common/
│ │ │ ├── Button.tsx
│ │ │ ├── Input.tsx
│ │ │ └── Card.tsx
│ │ └── specific/
│ ├── navigation/
│ │ ├── AppNavigator.tsx
│ │ ├── AuthNavigator.tsx
│ │ └── types.ts
│ ├── store/ # Redux/Zustand
│ │ ├── slices/
│ │ ├── hooks.ts
│ │ └── index.ts
│ ├── services/
│ │ ├── api/
│ │ │ ├── client.ts
│ │ │ └── endpoints/
│ │ └── storage/
│ ├── hooks/
│ │ ├── useAuth.ts
│ │ ├── useAsync.ts
│ │ └── useDebounce.ts
│ ├── utils/
│ │ ├── validation.ts
│ │ └── formatting.ts
│ ├── constants/
│ │ ├── colors.ts
│ │ ├── sizes.ts
│ │ └── api.ts
│ ├── types/
│ │ └── index.ts
│ └── assets/
│ ├── images/
│ └── fonts/
├── __tests__/
└── .env.example
```
3. **Generate App Entry Point** (Expo):
```typescript
import 'react-native-gesture-handler';
import { StatusBar } from 'expo-status-bar';
import { Provider } from 'react-redux';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { NavigationContainer } from '@react-navigation/native';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { store } from './src/store';
import AppNavigator from './src/navigation/AppNavigator';
import { ErrorBoundary } from './src/components/ErrorBoundary';
const queryClient = new QueryClient();
export default function App() {
return (
<ErrorBoundary>
<Provider store={store}>
<QueryClientProvider client={queryClient}>
<SafeAreaProvider>
<NavigationContainer>
<AppNavigator />
<StatusBar style="auto" />
</NavigationContainer>
</SafeAreaProvider>
</QueryClientProvider>
</Provider>
</ErrorBoundary>
);
}
```
4. **Generate Navigation**:
```typescript
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { HomeScreen, ProfileScreen, SettingsScreen } from '../screens';
const Stack = createNativeStackNavigator();
const Tab = createBottomTabNavigator();
function TabNavigator() {
return (
<Tab.Navigator screenOptions={{ headerShown: false }}>
<Tab.Screen name="Home" component={HomeScreen} />
<Tab.Screen name="Profile" component={ProfileScreen} />
<Tab.Screen name="Settings" component={SettingsScreen} />
</Tab.Navigator>
);
}
export default function AppNavigator() {
const isAuthenticated = useSelector(state => state.auth.isAuthenticated);
return (
<Stack.Navigator>
{isAuthenticated ? (
<Stack.Screen name="Main" component={TabNavigator} />
) : (
<Stack.Screen name="Auth" component={AuthScreen} />
)}
</Stack.Navigator>
);
}
```
5. **Generate API Client**:
```typescript
import axios from 'axios';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { API_BASE_URL } from '../constants/api';
const api = axios.create({
baseURL: API_BASE_URL,
timeout: 10000,
});
// Request interceptor
api.interceptors.request.use(async (config) => {
const token = await AsyncStorage.getItem('auth_token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// Response interceptor
api.interceptors.response.use(
(response) => response,
async (error) => {
if (error.response?.status === 401) {
await AsyncStorage.removeItem('auth_token');
// Navigate to login
}
return Promise.reject(error);
}
);
export default api;
```
6. **Generate package.json**:
```json
{
"name": "my-app",
"version": "1.0.0",
"main": "node_modules/expo/AppEntry.js",
"scripts": {
"start": "expo start",
"android": "expo run:android",
"ios": "expo run:ios",
"web": "expo start --web",
"test": "jest",
"lint": "eslint .",
"type-check": "tsc --noEmit"
},
"dependencies": {
"expo": "~49.0.0",
"react": "18.2.0",
"react-native": "0.72.0",
"@react-navigation/native": "^6.1.0",
"@react-navigation/native-stack": "^6.9.0",
"@react-navigation/bottom-tabs": "^6.5.0",
"react-native-safe-area-context": "4.6.3",
"react-native-screens": "~3.22.0",
"@reduxjs/toolkit": "^1.9.0",
"react-redux": "^8.1.0",
"@tanstack/react-query": "^4.35.0",
"axios": "^1.5.0",
"@react-native-async-storage/async-storage": "1.18.2",
"react-native-gesture-handler": "~2.12.0"
},
"devDependencies": {
"@types/react": "~18.2.14",
"typescript": "^5.1.3",
"@testing-library/react-native": "^12.3.0",
"jest": "^29.2.1"
}
}
```
### Best Practices Included:
- TypeScript configuration
- Navigation setup
- State management
- API client with interceptors
- Error boundaries
- Proper folder structure
- AsyncStorage for persistence
- Testing setup
- ESLint and TypeScript
### Example Usage:
```
User: "Scaffold Expo app with Redux and React Navigation"
Result: Complete Expo project with all configurations
```

256
commands/build-config.md Normal file
View File

@@ -0,0 +1,256 @@
# Build Configuration
Generate build configurations for iOS and Android.
## Task
You are a React Native build expert. Generate complete build configurations for production releases.
### Steps:
1. **Ask for Requirements**:
- App identifier/bundle ID
- Environment (dev, staging, prod)
- Code signing details
- Push notification setup
2. **Generate app.json** (Expo):
```json
{
"expo": {
"name": "My App",
"slug": "my-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": "com.company.myapp",
"buildNumber": "1",
"infoPlist": {
"NSCameraUsageDescription": "This app uses the camera to...",
"NSPhotoLibraryUsageDescription": "This app accesses photos to...",
"NSLocationWhenInUseUsageDescription": "This app uses location to..."
},
"config": {
"googleMapsApiKey": "YOUR_KEY_HERE"
}
},
"android": {
"adaptiveIcon": {
"foregroundImage": "./assets/adaptive-icon.png",
"backgroundColor": "#ffffff"
},
"package": "com.company.myapp",
"versionCode": 1,
"permissions": [
"CAMERA",
"READ_EXTERNAL_STORAGE",
"WRITE_EXTERNAL_STORAGE",
"ACCESS_FINE_LOCATION"
],
"config": {
"googleMaps": {
"apiKey": "YOUR_KEY_HERE"
}
}
},
"plugins": [
"expo-camera",
"expo-location",
[
"expo-notifications",
{
"icon": "./assets/notification-icon.png",
"color": "#ffffff"
}
]
],
"extra": {
"eas": {
"projectId": "your-project-id"
}
}
}
}
```
3. **Generate eas.json** (Expo EAS Build):
```json
{
"cli": {
"version": ">= 5.0.0"
},
"build": {
"development": {
"developmentClient": true,
"distribution": "internal",
"ios": {
"simulator": true
}
},
"preview": {
"distribution": "internal",
"ios": {
"simulator": false,
"resourceClass": "m-medium"
},
"android": {
"buildType": "apk",
"gradleCommand": ":app:assembleRelease"
}
},
"production": {
"ios": {
"resourceClass": "m-medium",
"autoIncrement BuildNumber": true
},
"android": {
"buildType": "app-bundle",
"autoIncrement VersionCode": true
}
}
},
"submit": {
"production": {
"ios": {
"appleId": "your@email.com",
"ascAppId": "1234567890",
"appleTeamId": "ABCD1234"
},
"android": {
"serviceAccountKeyPath": "./service-account.json",
"track": "production"
}
}
}
}
```
4. **Generate Environment Variables**:
```typescript
// config/env.ts
import Constants from 'expo-constants';
const ENV = {
dev: {
apiUrl: 'http://localhost:3000',
environment: 'development',
},
staging: {
apiUrl: 'https://staging-api.example.com',
environment: 'staging',
},
prod: {
apiUrl: 'https://api.example.com',
environment: 'production',
},
};
const getEnvVars = (env = Constants.manifest?.releaseChannel) => {
if (__DEV__) return ENV.dev;
if (env === 'staging') return ENV.staging;
return ENV.prod;
};
export default getEnvVars();
```
5. **Generate Build Scripts**:
```json
// package.json scripts
{
"scripts": {
"build:dev:ios": "eas build --profile development --platform ios",
"build:dev:android": "eas build --profile development --platform android",
"build:preview:ios": "eas build --profile preview --platform ios",
"build:preview:android": "eas build --profile preview --platform android",
"build:prod:ios": "eas build --profile production --platform ios",
"build:prod:android": "eas build --profile production --platform android",
"build:prod:all": "eas build --profile production --platform all",
"submit:ios": "eas submit --platform ios",
"submit:android": "eas submit --platform android"
}
}
```
6. **Generate CI/CD Configuration** (GitHub Actions):
```yaml
name: EAS Build
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 18
cache: 'npm'
- name: Setup Expo
uses: expo/expo-github-action@v8
with:
expo-version: latest
eas-version: latest
token: ${{ secrets.EXPO_TOKEN }}
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Build iOS
run: eas build --profile production --platform ios --non-interactive
if: github.ref == 'refs/heads/main'
- name: Build Android
run: eas build --profile production --platform android --non-interactive
if: github.ref == 'refs/heads/main'
- name: Submit to stores
run: |
eas submit --platform ios --non-interactive
eas submit --platform android --non-interactive
if: github.ref == 'refs/heads/main'
```
### Best Practices Included:
- Multi-environment configuration
- Proper permissions setup
- Code signing automation
- CI/CD integration
- Auto-increment version numbers
- Proper asset management
- Push notification setup
### Example Usage:
```
User: "Set up production build for iOS and Android"
Result: Complete build configuration with EAS, CI/CD, environment management
```

289
commands/screen-generate.md Normal file
View File

@@ -0,0 +1,289 @@
# Screen Generator
Generate React Native screens with navigation integration.
## Task
You are a React Native expert. Generate complete, production-ready screens with proper typing and navigation.
### Steps:
1. **Ask for Requirements**:
- Screen name and purpose
- Required data/API calls
- Form inputs (if any)
- Navigation params
2. **Generate Screen Component**:
```typescript
import React, { useEffect, useState } from 'react';
import {
View,
Text,
StyleSheet,
FlatList,
RefreshControl,
ActivityIndicator,
} from 'react-native';
import { NativeStackScreenProps } from '@react-navigation/native-stack';
import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '../../services/api';
import { Product } from '../../types';
import { ProductCard } from '../../components/ProductCard';
import { RootStackParamList } from '../../navigation/types';
type Props = NativeStackScreenProps<RootStackParamList, 'ProductList'>;
export function ProductListScreen({ navigation, route }: Props) {
const { category } = route.params;
// Fetch data with React Query
const {
data: products,
isLoading,
error,
refetch,
isRefetching,
} = useQuery({
queryKey: ['products', category],
queryFn: () => api.getProducts({ category }),
});
// Handle item press
const handleProductPress = (productId: string) => {
navigation.navigate('ProductDetail', { productId });
};
// Render loading state
if (isLoading) {
return (
<View style={styles.centerContainer}>
<ActivityIndicator size="large" />
</View>
);
}
// Render error state
if (error) {
return (
<View style={styles.centerContainer}>
<Text style={styles.errorText}>
Failed to load products
</Text>
</View>
);
}
// Render list
return (
<View style={styles.container}>
<FlatList
data={products}
keyExtractor={(item) => item.id}
renderItem={({ item }) => (
<ProductCard
product={item}
onPress={() => handleProductPress(item.id)}
/>
)}
contentContainerStyle={styles.listContent}
refreshControl={
<RefreshControl
refreshing={isRefetching}
onRefresh={refetch}
/>
}
ListEmptyComponent={
<Text style={styles.emptyText}>
No products found
</Text>
}
/>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#fff',
},
centerContainer: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
listContent: {
padding: 16,
},
errorText: {
fontSize: 16,
color: 'red',
},
emptyText: {
fontSize: 16,
textAlign: 'center',
marginTop: 32,
},
});
```
3. **Generate Form Screen**:
```typescript
import React from 'react';
import {
View,
StyleSheet,
ScrollView,
KeyboardAvoidingView,
Platform,
} from 'react-native';
import { useForm, Controller } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';
import { Input } from '../../components/Input';
import { Button } from '../../components/Button';
import { api } from '../../services/api';
const schema = z.object({
name: z.string().min(1, 'Name is required'),
email: z.string().email('Invalid email'),
phone: z.string().regex(/^\d{10}$/, 'Invalid phone number'),
});
type FormData = z.infer<typeof schema>;
export function ProfileEditScreen({ navigation }: Props) {
const {
control,
handleSubmit,
formState: { errors, isSubmitting },
} = useForm<FormData>({
resolver: zodResolver(schema),
defaultValues: {
name: '',
email: '',
phone: '',
},
});
const onSubmit = async (data: FormData) => {
try {
await api.updateProfile(data);
navigation.goBack();
} catch (error) {
console.error('Failed to update profile', error);
}
};
return (
<KeyboardAvoidingView
style={styles.container}
behavior={Platform.OS === 'ios' ? 'padding' : undefined}
>
<ScrollView
contentContainerStyle={styles.content}
keyboardShouldPersistTaps="handled"
>
<Controller
control={control}
name="name"
render={({ field: { onChange, value } }) => (
<Input
label="Name"
value={value}
onChangeText={onChange}
error={errors.name?.message}
/>
)}
/>
<Controller
control={control}
name="email"
render={({ field: { onChange, value } }) => (
<Input
label="Email"
value={value}
onChangeText={onChange}
keyboardType="email-address"
autoCapitalize="none"
error={errors.email?.message}
/>
)}
/>
<Controller
control={control}
name="phone"
render={({ field: { onChange, value } }) => (
<Input
label="Phone"
value={value}
onChangeText={onChange}
keyboardType="phone-pad"
error={errors.phone?.message}
/>
)}
/>
<Button
title="Save"
onPress={handleSubmit(onSubmit)}
loading={isSubmitting}
/>
</ScrollView>
</KeyboardAvoidingView>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#fff',
},
content: {
padding: 16,
},
});
```
4. **Generate Navigation Types**:
```typescript
// navigation/types.ts
export type RootStackParamList = {
ProductList: { category: string };
ProductDetail: { productId: string };
ProfileEdit: undefined;
};
declare global {
namespace ReactNavigation {
interface RootParamList extends RootStackParamList {}
}
}
```
### Best Practices Included:
- TypeScript types
- React Query for data fetching
- React Hook Form for forms
- Zod validation
- Proper error handling
- Loading states
- Pull-to-refresh
- Keyboard handling
- Responsive styling
### Example Usage:
```
User: "Generate product list screen with pull-to-refresh"
Result: Complete screen with navigation, data fetching, error handling
```

85
plugin.lock.json Normal file
View File

@@ -0,0 +1,85 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:anton-abyzov/specweave:plugins/specweave-mobile",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "221aa8b2b6e0177627327e99ffae94055ea72d16",
"treeHash": "e96d1cc4b60a6d9953a5924686f89e51cff01a9ca12a03c74dbe18c07f75d143",
"generatedAt": "2025-11-28T10:13:53.071108Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "specweave-mobile",
"description": "Comprehensive React Native and Expo development support for mobile app development. Includes environment setup, debugging, performance optimization, native modules, and testing strategies.",
"version": "0.22.14"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "21b156db2bfeea959a3574c60e2bc853c6276f55b2f1327bd000a6c647215509"
},
{
"path": "agents/mobile-architect/AGENT.md",
"sha256": "b8ebcad44d4c2e1831b1c248ca47c92e69e691666fe2eb039879b0bb9cf1475d"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "386fac661e08c75cca6f34ca76b5e54d0f72198e57aeff052239b25b0e3362d3"
},
{
"path": "commands/build-config.md",
"sha256": "10a99d1404b33c5612ba726a9f3e6587d99881523b94e3841afbacf9eee3c230"
},
{
"path": "commands/screen-generate.md",
"sha256": "c047fe97c361436d1ac88c4fa736e453c63b5434e463b29d481dd8ae19c0ef7c"
},
{
"path": "commands/app-scaffold.md",
"sha256": "b37f660c5b0987a5520b20a4b22829637eb5a8f6bd1e31152cc84c34ed8ff03f"
},
{
"path": "skills/device-testing/SKILL.md",
"sha256": "549fbf7a5467115ad6009cc7d3815f721b2c4121e9a3663618b8094ba140b199"
},
{
"path": "skills/react-native-setup/SKILL.md",
"sha256": "2da071871613e29326d70f74b124a8efb16f2946c41b4f8312f582d2e8e62f43"
},
{
"path": "skills/mobile-debugging/SKILL.md",
"sha256": "191e1c46427fa7ed5d1c87e6ca68a89c75348b9f09db93a0fbde6f0a737c6a6c"
},
{
"path": "skills/expo-workflow/SKILL.md",
"sha256": "e899849b8f1410e8c6d2ac817739a8c7ffa68be2239074366eea3d7d8280fada"
},
{
"path": "skills/metro-bundler/SKILL.md",
"sha256": "e616b570f5fdfafbbd3535704660f3164cc537eeb3517c850b5247e3c4140979"
},
{
"path": "skills/performance-optimization/SKILL.md",
"sha256": "376a1cbff150b59573f14e742c93ca6c0385115c7e13d7f775c42f827e6d5e28"
},
{
"path": "skills/native-modules/SKILL.md",
"sha256": "10056d490505ffa538f29ccb475545980615a994f238f8d4a4999d0a422066ef"
}
],
"dirSha256": "e96d1cc4b60a6d9953a5924686f89e51cff01a9ca12a03c74dbe18c07f75d143"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

609
skills/device-testing/SKILL.md Normal file
View File

@@ -0,0 +1,609 @@
---
name: device-testing
description: Expert in React Native testing strategies including unit tests with Jest, integration tests, E2E tests with Detox, component testing with React Native Testing Library, snapshot testing, mocking native modules, testing on simulators and real devices. Activates for testing, jest, detox, e2e, unit test, integration test, component test, test runner, mock, snapshot test, testing library, react native testing library, test automation.
---
# Device Testing Expert
Comprehensive expertise in React Native testing strategies, from unit tests to end-to-end testing on real devices and simulators. Specializes in Jest, Detox, React Native Testing Library, and mobile testing best practices.
## What I Know
### Testing Pyramid for Mobile
**Three Layers**
1. **Unit Tests** (70%): Fast, isolated, test logic
2. **Integration Tests** (20%): Test component integration
3. **E2E Tests** (10%): Test full user flows on devices
**Tools**
- **Jest**: Unit and integration testing
- **React Native Testing Library**: Component testing
- **Detox**: E2E testing on simulators/emulators
- **Maestro**: Alternative E2E testing (newer)
### Unit Testing with Jest
**Basic Component Test**
```javascript
// UserProfile.test.js
import React from 'react';
import { render, fireEvent } from '@testing-library/react-native';
import UserProfile from './UserProfile';
describe('UserProfile', () => {
it('renders user name correctly', () => {
const user = { name: 'John Doe', email: 'john@example.com' };
const { getByText } = render(<UserProfile user={user} />);
expect(getByText('John Doe')).toBeTruthy();
expect(getByText('john@example.com')).toBeTruthy();
});
it('calls onPress when button is pressed', () => {
const onPress = jest.fn();
const { getByText } = render(
<UserProfile user={{ name: 'John' }} onPress={onPress} />
);
fireEvent.press(getByText('Edit Profile'));
expect(onPress).toHaveBeenCalledTimes(1);
});
});
```
**Testing Hooks**
```javascript
// useCounter.test.js
import { renderHook, act } from '@testing-library/react-hooks';
import useCounter from './useCounter';
describe('useCounter', () => {
it('increments counter', () => {
const { result } = renderHook(() => useCounter());
act(() => {
result.current.increment();
});
expect(result.current.count).toBe(1);
});
it('decrements counter', () => {
const { result } = renderHook(() => useCounter(5));
act(() => {
result.current.decrement();
});
expect(result.current.count).toBe(4);
});
});
```
**Async Testing**
```javascript
// api.test.js
import { fetchUser } from './api';
describe('fetchUser', () => {
it('fetches user data successfully', async () => {
const user = await fetchUser('123');
expect(user).toEqual({
id: '123',
name: 'John Doe',
email: 'john@example.com'
});
});
it('handles errors gracefully', async () => {
await expect(fetchUser('invalid')).rejects.toThrow('User not found');
});
});
```
**Snapshot Testing**
```javascript
// Button.test.js
import React from 'react';
import { render } from '@testing-library/react-native';
import Button from './Button';
describe('Button', () => {
it('renders correctly', () => {
const { toJSON } = render(<Button title="Press Me" />);
expect(toJSON()).toMatchSnapshot();
});
it('renders with custom color', () => {
const { toJSON } = render(<Button title="Press Me" color="red" />);
expect(toJSON()).toMatchSnapshot();
});
});
```
### Mocking
**Mocking Native Modules**
```javascript
// __mocks__/react-native-camera.js
export const RNCamera = {
Constants: {
Type: {
back: 'back',
front: 'front'
}
}
};
// In test file
jest.mock('react-native-camera', () => require('./__mocks__/react-native-camera'));
// Or inline mock
jest.mock('react-native-camera', () => ({
RNCamera: {
Constants: {
Type: { back: 'back', front: 'front' }
}
}
}));
```
**Mocking AsyncStorage**
```javascript
// Setup file (jest.setup.js)
import mockAsyncStorage from '@react-native-async-storage/async-storage/jest/async-storage-mock';
jest.mock('@react-native-async-storage/async-storage', () => mockAsyncStorage);
// In test
import AsyncStorage from '@react-native-async-storage/async-storage';
describe('Storage', () => {
beforeEach(() => {
AsyncStorage.clear();
});
it('stores and retrieves data', async () => {
await AsyncStorage.setItem('key', 'value');
const value = await AsyncStorage.getItem('key');
expect(value).toBe('value');
});
});
```
**Mocking Navigation**
```javascript
// Mock React Navigation
jest.mock('@react-navigation/native', () => ({
useNavigation: () => ({
navigate: jest.fn(),
goBack: jest.fn()
})
}));
// In test
import { useNavigation } from '@react-navigation/native';
describe('ProfileScreen', () => {
it('navigates to settings on button press', () => {
const navigate = jest.fn();
useNavigation.mockReturnValue({ navigate });
const { getByText } = render(<ProfileScreen />);
fireEvent.press(getByText('Settings'));
expect(navigate).toHaveBeenCalledWith('Settings');
});
});
```
**Mocking API Calls**
```javascript
// Using jest.mock
jest.mock('./api', () => ({
fetchUser: jest.fn(() => Promise.resolve({
id: '123',
name: 'Mock User'
}))
}));
// Using MSW (Mock Service Worker)
import { rest } from 'msw';
import { setupServer } from 'msw/node';
const server = setupServer(
rest.get('/api/user/:id', (req, res, ctx) => {
return res(ctx.json({
id: req.params.id,
name: 'Mock User'
}));
})
);
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```
### Component Testing with React Native Testing Library
**Queries**
```javascript
import { render, screen } from '@testing-library/react-native';
// By text
screen.getByText('Submit');
screen.findByText('Loading...'); // Async
screen.queryByText('Error'); // Returns null if not found
// By testID
<View testID="profile-container" />
screen.getByTestId('profile-container');
// By placeholder
<TextInput placeholder="Enter email" />
screen.getByPlaceholderText('Enter email');
// By display value
screen.getByDisplayValue('john@example.com');
// Multiple queries
screen.getAllByText('Item'); // Returns array
```
**User Interactions**
```javascript
import { render, fireEvent, waitFor } from '@testing-library/react-native';
describe('LoginForm', () => {
it('submits form with valid data', async () => {
const onSubmit = jest.fn();
const { getByPlaceholderText, getByText } = render(
<LoginForm onSubmit={onSubmit} />
);
// Type into inputs
fireEvent.changeText(getByPlaceholderText('Email'), 'test@example.com');
fireEvent.changeText(getByPlaceholderText('Password'), 'password123');
// Press button
fireEvent.press(getByText('Login'));
// Wait for async operation
await waitFor(() => {
expect(onSubmit).toHaveBeenCalledWith({
email: 'test@example.com',
password: 'password123'
});
});
});
});
```
### E2E Testing with Detox
**Installation**
```bash
# Install Detox
npm install --save-dev detox
# iOS: Install dependencies
brew tap wix/brew
brew install applesimutils
# Initialize Detox
detox init
# Build app for testing (iOS)
detox build --configuration ios.sim.debug
# Run tests
detox test --configuration ios.sim.debug
```
**Configuration (.detoxrc.js)**
```javascript
module.exports = {
testRunner: 'jest',
runnerConfig: 'e2e/config.json',
apps: {
'ios.debug': {
type: 'ios.app',
binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/MyApp.app',
build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build'
},
'android.debug': {
type: 'android.apk',
binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug'
}
},
devices: {
simulator: {
type: 'ios.simulator',
device: { type: 'iPhone 15 Pro' }
},
emulator: {
type: 'android.emulator',
device: { avdName: 'Pixel_6_API_34' }
}
},
configurations: {
'ios.sim.debug': {
device: 'simulator',
app: 'ios.debug'
},
'android.emu.debug': {
device: 'emulator',
app: 'android.debug'
}
}
};
```
**Writing Detox Tests**
```javascript
// e2e/login.test.js
describe('Login Flow', () => {
beforeAll(async () => {
await device.launchApp();
});
beforeEach(async () => {
await device.reloadReactNative();
});
it('should login successfully with valid credentials', async () => {
// Type email
await element(by.id('email-input')).typeText('test@example.com');
// Type password
await element(by.id('password-input')).typeText('password123');
// Tap login button
await element(by.id('login-button')).tap();
// Verify navigation to home screen
await expect(element(by.id('home-screen'))).toBeVisible();
});
it('should show error with invalid credentials', async () => {
await element(by.id('email-input')).typeText('invalid@example.com');
await element(by.id('password-input')).typeText('wrong');
await element(by.id('login-button')).tap();
await expect(element(by.text('Invalid credentials'))).toBeVisible();
});
it('should scroll to bottom of list', async () => {
await element(by.id('user-list')).scrollTo('bottom');
await expect(element(by.id('load-more-button'))).toBeVisible();
});
});
```
**Advanced Detox Actions**
```javascript
// Swipe
await element(by.id('carousel')).swipe('left', 'fast', 0.75);
// Scroll
await element(by.id('scroll-view')).scroll(200, 'down');
// Long press
await element(by.id('item-1')).longPress();
// Multi-tap
await element(by.id('like-button')).multiTap(2);
// Wait for element
await waitFor(element(by.id('success-message')))
.toBeVisible()
.withTimeout(5000);
// Take screenshot
await device.takeScreenshot('login-success');
```
### Maestro (Alternative E2E Tool)
**Installation**
```bash
# Install Maestro
curl -Ls "https://get.maestro.mobile.dev" | bash
# Verify installation
maestro --version
```
**Maestro Flow (YAML-based)**
```yaml
# flows/login.yaml
appId: com.myapp
---
# Launch app
- launchApp
# Wait for login screen
- assertVisible: "Login"
# Enter credentials
- tapOn: "Email"
- inputText: "test@example.com"
- tapOn: "Password"
- inputText: "password123"
# Submit
- tapOn: "Login"
# Verify success
- assertVisible: "Welcome"
```
**Run Maestro Flow**
```bash
# iOS Simulator
maestro test flows/login.yaml
# Android Emulator
maestro test --platform android flows/login.yaml
# Real device (USB connected)
maestro test --device <device-id> flows/login.yaml
```
## When to Use This Skill
Ask me when you need help with:
- Setting up Jest for React Native
- Writing unit tests for components and hooks
- Mocking native modules and dependencies
- Writing integration tests
- Setting up Detox or Maestro for E2E testing
- Testing asynchronous operations
- Snapshot testing strategies
- Testing navigation flows
- Debugging test failures
- Running tests in CI/CD pipelines
- Testing on real devices
- Performance testing strategies
## Test Configuration
**Jest Configuration (jest.config.js)**
```javascript
module.exports = {
preset: 'react-native',
setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
transformIgnorePatterns: [
'node_modules/(?!(react-native|@react-native|@react-navigation|expo|@expo)/)'
],
collectCoverageFrom: [
'src/**/*.{js,jsx,ts,tsx}',
'!src/**/*.test.{js,jsx,ts,tsx}',
'!src/**/__tests__/**'
],
coverageThreshold: {
global: {
statements: 80,
branches: 75,
functions: 80,
lines: 80
}
}
};
```
**Jest Setup (jest.setup.js)**
```javascript
import 'react-native-gesture-handler/jestSetup';
// Mock native modules
jest.mock('react-native/Libraries/Animated/NativeAnimatedHelper');
// Mock AsyncStorage
import mockAsyncStorage from '@react-native-async-storage/async-storage/jest/async-storage-mock';
jest.mock('@react-native-async-storage/async-storage', () => mockAsyncStorage);
// Global test utilities
global.fetch = jest.fn();
// Silence console warnings in tests
global.console = {
...console,
warn: jest.fn(),
error: jest.fn()
};
```
## Pro Tips & Tricks
### 1. Test IDs for E2E Testing
Add testID to components for reliable selectors:
```javascript
// In component
<TouchableOpacity testID="submit-button" onPress={handleSubmit}>
<Text>Submit</Text>
</TouchableOpacity>
// In Detox test
await element(by.id('submit-button')).tap();
// Avoid using text or accessibility labels (can change with i18n)
```
### 2. Test Factories for Mock Data
```javascript
// testUtils/factories.js
export const createMockUser = (overrides = {}) => ({
id: '123',
name: 'John Doe',
email: 'john@example.com',
...overrides
});
// In test
const user = createMockUser({ name: 'Jane Doe' });
```
### 3. Custom Render with Providers
```javascript
// testUtils/render.js
import { render } from '@testing-library/react-native';
import { NavigationContainer } from '@react-navigation/native';
import { Provider } from 'react-redux';
import { store } from '../store';
export function renderWithProviders(ui, options = {}) {
return render(
<Provider store={store}>
<NavigationContainer>
{ui}
</NavigationContainer>
</Provider>,
options
);
}
// In test
import { renderWithProviders } from './testUtils/render';
renderWithProviders(<MyScreen />);
```
### 4. Parallel Test Execution
```json
// package.json
{
"scripts": {
"test": "jest --maxWorkers=4",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage"
}
}
```
## Integration with SpecWeave
**Test Planning**
- Document test strategy in `spec.md`
- Include test coverage targets in `tasks.md`
- Embed test cases in tasks (BDD format)
**Coverage Tracking**
- Set coverage thresholds (80%+ for critical paths)
- Track coverage trends across increments
- Document testing gaps in increment reports
**CI/CD Integration**
- Run tests on every commit
- Block merges if tests fail
- Generate coverage reports
- Run E2E tests on staging builds

440
skills/expo-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,440 @@
---
name: expo-workflow
description: Expert in Expo development workflows, EAS Build, EAS Update, Expo Go, dev clients, expo-cli commands, app configuration, and deployment strategies. Activates for expo, expo go, eas build, eas update, expo config, app.json, eas.json, expo dev client, expo prebuild, expo eject, over-the-air updates, expo doctor, expo install, managed workflow, bare workflow.
---
# Expo Workflow Expert
Comprehensive expertise in Expo development workflows, EAS (Expo Application Services), and optimization strategies for rapid mobile development. Specializes in modern Expo SDK features, development builds, and deployment pipelines.
## What I Know
### Expo Fundamentals
**Managed vs Bare Workflow**
- Managed workflow: Full Expo SDK, minimal native code
- Bare workflow: Full native code access with Expo modules
- When to use each approach
- Migration strategies between workflows
**Expo Go vs Development Builds**
- Expo Go: Quick testing, limited native modules
- Dev Client: Full native module support, custom builds
- When to switch from Expo Go to dev builds
- Creating custom dev clients with EAS Build
**Expo SDK & Modules**
- Core Expo modules (expo-camera, expo-location, etc.)
- Third-party native module compatibility
- Module installation best practices
- Autolinking and manual linking
### EAS Build (Cloud Builds)
**Build Profiles**
- Development builds: Fast iteration, dev client
- Preview builds: Internal testing, TestFlight/Internal Testing
- Production builds: App Store/Play Store submission
- Custom build profiles in eas.json
**Platform-Specific Configuration**
- iOS credentials management
- Android keystore handling
- Build caching strategies
- Environment variable injection
**Build Optimization**
- Caching node_modules and gradle dependencies
- Incremental builds
- Build machine types (M1, Ubuntu)
- Build time reduction strategies
### EAS Update (OTA Updates)
**Over-The-Air Updates**
- JavaScript bundle updates without app store submission
- Update channels and branches
- Rollout strategies (gradual rollout, instant rollout)
- Rollback capabilities
**Update Workflows**
- Development channel: Continuous updates
- Preview channel: QA testing
- Production channel: Staged rollouts
- Emergency hotfix workflows
**Update Best Practices**
- Version compatibility management
- Update frequency optimization
- Monitoring update adoption
- Handling update failures gracefully
### App Configuration
**app.json / app.config.js**
- App metadata (name, slug, version)
- Platform-specific configurations
- Asset and icon configuration
- Splash screen customization
- Deep linking setup (scheme, associated domains)
- Permissions configuration
- Build-time environment variables
**eas.json**
- Build profile configuration
- Submit profile setup
- Environment secrets management
- Platform-specific build settings
**Dynamic Configuration**
- Environment-specific configs (dev, staging, prod)
- Feature flags integration
- App variants (white-label apps)
### Development Workflow
**Fast Refresh & Hot Reloading**
- Understanding fast refresh behavior
- Troubleshooting fast refresh issues
- When to use full reload vs fast refresh
**Debugging Tools**
- React DevTools integration
- Remote debugging with Chrome DevTools
- Flipper for advanced debugging
- Network request inspection
- Performance profiling
**Local Development**
- Running on physical devices (QR code scanning)
- Running on simulators/emulators
- Offline development strategies
- Tunnel mode vs LAN mode
### Deployment & Distribution
**App Store Submission**
- iOS: TestFlight, App Store Connect integration
- Android: Internal testing, Play Store submission
- EAS Submit command automation
- Store metadata management
**Internal Distribution**
- Ad-hoc iOS builds
- Android APK distribution
- Enterprise distribution
- TestFlight external testing
**CI/CD Integration**
- GitHub Actions with EAS Build
- GitLab CI integration
- Automated build triggers
- Automated OTA updates on merge
## When to Use This Skill
Ask me when you need help with:
- Setting up Expo development workflow
- Creating development builds with EAS Build
- Configuring app.json or eas.json
- Setting up over-the-air updates with EAS Update
- Troubleshooting Expo Go limitations
- Optimizing build times
- Managing app credentials and secrets
- Configuring deep linking and URL schemes
- Setting up CI/CD pipelines for Expo apps
- Deploying to App Store or Play Store
- Understanding Expo SDK capabilities
- Migrating from Expo Go to dev client
- Handling native modules in Expo projects
## Essential Expo Commands
### Project Setup
```bash
# Create new Expo project
npx create-expo-app@latest MyApp
# Navigate to project
cd MyApp
# Start development server
npx expo start
# Install Expo module
npx expo install expo-camera
# Check project health
npx expo-doctor
```
### Development
```bash
# Start with cache cleared
npx expo start -c
# Start with specific mode
npx expo start --dev-client # Development build
npx expo start --go # Expo Go
# Run on specific platform
npx expo run:ios
npx expo run:android
# Prebuild native projects (bare workflow)
npx expo prebuild
```
### EAS Build
```bash
# Login to EAS
eas login
# Configure EAS
eas build:configure
# Build for all platforms
eas build --platform all
# Build development version
eas build --profile development --platform ios
# Build for production
eas build --profile production --platform all
# Check build status
eas build:list
```
### EAS Update
```bash
# Configure EAS Update
eas update:configure
# Publish update to default channel
eas update --branch production --message "Fix critical bug"
# Publish to specific channel
eas update --channel preview --message "QA testing"
# List published updates
eas update:list
# Rollback update
eas update:rollback
```
### EAS Submit
```bash
# Submit to App Store
eas submit --platform ios
# Submit to Play Store
eas submit --platform android
# Submit specific build
eas submit --platform ios --id <build-id>
```
## Pro Tips & Tricks
### 1. Development Build Optimization
Create a reusable development build once, then use EAS Update for daily changes:
```json
// eas.json
{
"build": {
"development": {
"developmentClient": true,
"distribution": "internal",
"ios": {
"simulator": true
}
}
}
}
```
Build once:
```bash
eas build --profile development --platform all
```
Update JavaScript daily:
```bash
eas update --branch development --message "Daily changes"
```
### 2. Environment-Based Configuration
Use app.config.js for dynamic configuration:
```javascript
// app.config.js
export default ({ config }) => {
const isProduction = process.env.APP_ENV === 'production';
return {
...config,
name: isProduction ? 'MyApp' : 'MyApp Dev',
slug: 'myapp',
extra: {
apiUrl: isProduction
? 'https://api.myapp.com'
: 'https://dev-api.myapp.com',
analyticsKey: process.env.ANALYTICS_KEY,
},
updates: {
url: 'https://u.expo.dev/your-project-id'
}
};
};
```
### 3. Fast Credential Setup
Let EAS manage credentials automatically:
```json
// eas.json
{
"build": {
"production": {
"ios": {
"credentialsSource": "remote"
},
"android": {
"credentialsSource": "remote"
}
}
}
}
```
### 4. Efficient Build Caching
Speed up builds by caching dependencies:
```json
// eas.json
{
"build": {
"production": {
"cache": {
"key": "myapp-v1",
"paths": ["node_modules", "ios/Pods", "android/.gradle"]
}
}
}
}
```
### 5. Gradual OTA Rollout
Safely deploy updates to production:
```bash
# Start with 10% rollout
eas update --branch production --message "New feature" --rollout-percentage 10
# Monitor metrics, then increase
eas update:configure-rollout --branch production --percentage 50
# Full rollout
eas update:configure-rollout --branch production --percentage 100
```
### 6. Quick Testing on Physical Devices
For Expo Go (quick testing):
```bash
# Start dev server
npx expo start
# Scan QR code with:
# - iOS: Camera app
# - Android: Expo Go app
```
For dev client (full features):
```bash
# Install dev client once
eas build --profile development --platform ios
# Daily JavaScript updates via EAS Update
eas update --branch development
```
### 7. Troubleshooting Common Issues
**"Unable to resolve module"**
```bash
# Clear Metro cache
npx expo start -c
# Reinstall dependencies
rm -rf node_modules && npm install
```
**"Build failed on EAS"**
```bash
# Check build logs
eas build:list
eas build:view <build-id>
# Run prebuild locally to catch issues early
npx expo prebuild
```
**"Update not appearing in app"**
```bash
# Check update channel matches app's channel
eas channel:list
# Verify update was published successfully
eas update:list --branch production
# Force reload in app (shake device → reload)
```
### 8. Native Module Integration
When you need a native module not in Expo SDK:
```bash
# Install the module
npm install react-native-awesome-module
# Prebuild to generate native projects
npx expo prebuild
# Rebuild dev client with new module
eas build --profile development --platform all
# Continue using EAS Update for JS changes
eas update --branch development
```
## Integration with SpecWeave
**Increment Planning**
- Document Expo setup steps in `spec.md`
- Include EAS Build/Update configuration in `plan.md`
- Track build and deployment tasks in `tasks.md`
**Testing Strategy**
- Use dev builds for feature development
- Preview builds for QA testing
- Production builds for stakeholder demos
**Living Documentation**
- Document build profiles in `.specweave/docs/internal/operations/`
- Track deployment procedures in runbooks
- Maintain credential management procedures
**Cost Optimization**
- Use EAS Update instead of rebuilding for JS-only changes
- Cache dependencies to reduce build times
- Monitor EAS usage in increment reports

614
skills/metro-bundler/SKILL.md Normal file
View File

@@ -0,0 +1,614 @@
---
name: metro-bundler
description: Expert in Metro bundler configuration, optimization, troubleshooting, caching strategies, custom transformers, asset management, source maps, bundling performance. Activates for metro, metro bundler, metro.config.js, bundler, bundle, cache, transformer, asset resolver, metro cache, bundling error, unable to resolve module, port 8081.
---
# Metro Bundler Expert
Comprehensive expertise in React Native's Metro bundler, including configuration, optimization, custom transformers, caching strategies, and troubleshooting common bundling issues.
## What I Know
### Metro Fundamentals
**What is Metro?**
- JavaScript bundler for React Native
- Transforms and bundles JavaScript modules
- Handles assets (images, fonts, etc.)
- Provides fast refresh for development
- Generates source maps for debugging
**Key Concepts**
- **Transformer**: Converts source code (TypeScript, JSX) to JavaScript
- **Resolver**: Locates modules in the file system
- **Serializer**: Combines modules into bundles
- **Cache**: Speeds up subsequent builds
### Metro Configuration
**Basic metro.config.js**
```javascript
const { getDefaultConfig } = require('expo/metro-config');
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);
module.exports = config;
```
**Custom Configuration**
```javascript
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(__dirname);
const config = {
transformer: {
// Enable Babel transformer
babelTransformerPath: require.resolve('react-native-svg-transformer'),
// Source map options
getTransformOptions: async () => ({
transform: {
experimentalImportSupport: false,
inlineRequires: true,
},
}),
},
resolver: {
// Custom asset extensions
assetExts: defaultConfig.resolver.assetExts.filter(ext => ext !== 'svg'),
// Custom source extensions
sourceExts: [...defaultConfig.resolver.sourceExts, 'svg', 'cjs'],
// Node module resolution
nodeModulesPaths: [
'./node_modules',
'../../node_modules', // For monorepos
],
// Custom platform-specific extensions
platforms: ['ios', 'android', 'native'],
},
server: {
// Custom port
port: 8081,
// Enhanced logging
enhanceMiddleware: (middleware) => {
return (req, res, next) => {
console.log(`Metro request: ${req.url}`);
return middleware(req, res, next);
};
},
},
watchFolders: [
// Watch external folders (monorepos)
path.resolve(__dirname, '..', 'shared-library'),
],
resetCache: true, // Reset cache on start (dev only)
};
module.exports = mergeConfig(defaultConfig, config);
```
### Optimization Strategies
**Inline Requires**
```javascript
// metro.config.js
module.exports = {
transformer: {
getTransformOptions: async () => ({
transform: {
inlineRequires: true, // Lazy load modules (faster startup)
},
}),
},
};
// Before (eager loading)
import UserProfile from './UserProfile';
import Settings from './Settings';
function App() {
return (
<View>
{showProfile ? <UserProfile /> : <Settings />}
</View>
);
}
// After inline requires (lazy loading)
function App() {
return (
<View>
{showProfile ?
<require('./UserProfile').default /> :
<require('./Settings').default />
}
</View>
);
}
```
**Bundle Splitting (Experimental)**
```javascript
// metro.config.js
module.exports = {
serializer: {
createModuleIdFactory: () => {
// Generate stable module IDs for better caching
return (path) => {
return require('crypto')
.createHash('sha1')
.update(path)
.digest('hex')
.substring(0, 8);
};
},
},
};
```
**Asset Optimization**
```javascript
// metro.config.js
module.exports = {
transformer: {
// Minify assets
minifierPath: require.resolve('metro-minify-terser'),
minifierConfig: {
compress: {
drop_console: true, // Remove console.log in production
drop_debugger: true,
},
output: {
comments: false,
},
},
},
resolver: {
// Optimize asset resolution
assetExts: [
'png', 'jpg', 'jpeg', 'gif', 'webp', // Images
'mp3', 'wav', 'm4a', 'aac', // Audio
'mp4', 'mov', // Video
'ttf', 'otf', 'woff', 'woff2', // Fonts
],
},
};
```
### Custom Transformers
**SVG Transformer**
```bash
# Install
npm install react-native-svg react-native-svg-transformer
# metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer = {
...config.transformer,
babelTransformerPath: require.resolve('react-native-svg-transformer'),
};
config.resolver = {
...config.resolver,
assetExts: config.resolver.assetExts.filter(ext => ext !== 'svg'),
sourceExts: [...config.resolver.sourceExts, 'svg'],
};
module.exports = config;
```
```javascript
// Usage in code
import Logo from './assets/logo.svg';
function App() {
return <Logo width={120} height={40} />;
}
```
**Multiple File Extensions**
```javascript
// metro.config.js
module.exports = {
resolver: {
// Add .web.js, .native.js for platform-specific code
sourceExts: ['js', 'json', 'ts', 'tsx', 'jsx', 'web.js', 'native.js'],
// Custom resolution logic
resolveRequest: (context, moduleName, platform) => {
if (moduleName === 'my-module') {
// Custom module resolution
return {
filePath: '/custom/path/to/module.js',
type: 'sourceFile',
};
}
return context.resolveRequest(context, moduleName, platform);
},
},
};
```
### Caching Strategies
**Cache Management**
```bash
# Clear Metro cache
npx react-native start --reset-cache
npm start -- --reset-cache # Expo
# Or manually
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
# Clear watchman cache
watchman watch-del-all
# Clear all caches (nuclear option)
npm run clear # If configured in package.json
```
**Cache Configuration**
```javascript
// metro.config.js
const path = require('path');
module.exports = {
cacheStores: [
// Custom cache directory
{
get: (key) => {
const cachePath = path.join(__dirname, '.metro-cache', key);
// Implement custom cache retrieval
},
set: (key, value) => {
const cachePath = path.join(__dirname, '.metro-cache', key);
// Implement custom cache storage
},
},
],
// Reset cache on config changes
resetCache: process.env.RESET_CACHE === 'true',
};
```
### Monorepo Setup
**Workspaces Configuration**
```javascript
// metro.config.js (in app directory)
const path = require('path');
const { getDefaultConfig } = require('@react-native/metro-config');
const projectRoot = __dirname;
const workspaceRoot = path.resolve(projectRoot, '../..');
const config = getDefaultConfig(projectRoot);
// Watch workspace directories
config.watchFolders = [workspaceRoot];
// Resolve modules from workspace
config.resolver.nodeModulesPaths = [
path.resolve(projectRoot, 'node_modules'),
path.resolve(workspaceRoot, 'node_modules'),
];
// Avoid hoisting issues
config.resolver.disableHierarchicalLookup = false;
module.exports = config;
```
**Symlink Handling**
```javascript
// metro.config.js
module.exports = {
resolver: {
// Enable symlink support
unstable_enableSymlinks: true,
// Resolve symlinked packages
resolveRequest: (context, moduleName, platform) => {
const resolution = context.resolveRequest(context, moduleName, platform);
if (resolution && resolution.type === 'sourceFile') {
// Resolve real path for symlinks
const realPath = require('fs').realpathSync(resolution.filePath);
return {
...resolution,
filePath: realPath,
};
}
return resolution;
},
},
};
```
### Common Issues & Solutions
**"Unable to resolve module"**
```bash
# Solution 1: Clear cache
npx react-native start --reset-cache
# Solution 2: Reinstall dependencies
rm -rf node_modules
npm install
# Solution 3: Check import paths
# Ensure case-sensitive imports match file names
import UserProfile from './userProfile'; # ❌ Wrong case
import UserProfile from './UserProfile'; # ✅ Correct
# Solution 4: Add to metro.config.js
module.exports = {
resolver: {
extraNodeModules: {
'my-module': path.resolve(__dirname, 'node_modules/my-module'),
},
},
};
```
**"Port 8081 already in use"**
```bash
# Find and kill process
lsof -ti:8081 | xargs kill -9
# Or start on different port
npx react-native start --port 8082
# Update code to use new port
adb reverse tcp:8082 tcp:8082 # Android
```
**"Invariant Violation: Module AppRegistry is not a registered callable module"**
```bash
# Clear all caches
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
watchman watch-del-all
rm -rf node_modules
npm install
npx react-native start --reset-cache
```
**"TransformError: ... SyntaxError"**
```javascript
// Add Babel plugin to metro.config.js
module.exports = {
transformer: {
babelTransformerPath: require.resolve('./customBabelTransformer.js'),
},
};
// customBabelTransformer.js
module.exports = require('metro-react-native-babel-preset');
```
## When to Use This Skill
Ask me when you need help with:
- Configuring Metro bundler
- Custom transformers (SVG, images, etc.)
- Optimizing bundle size and startup time
- Setting up monorepo with Metro
- Troubleshooting "Unable to resolve module" errors
- Clearing Metro cache effectively
- Configuring source maps
- Platform-specific file resolution
- Debugging bundling performance
- Custom asset handling
- Port conflicts (8081)
- Symlink resolution in monorepos
## Essential Commands
### Development
```bash
# Start Metro bundler
npx react-native start
# Start with cache cleared
npx react-native start --reset-cache
# Start with custom port
npx react-native start --port 8082
# Start with verbose logging
npx react-native start --verbose
# Expo dev server
npx expo start
# Expo with cache cleared
npx expo start -c
```
### Debugging
```bash
# Check Metro status
curl http://localhost:8081/status
# Get bundle (for debugging)
curl http://localhost:8081/index.bundle?platform=ios > bundle.js
# Check source map
curl http://localhost:8081/index.map?platform=ios > bundle.map
# List all modules in bundle
curl http://localhost:8081/index.bundle?platform=ios&dev=false&minify=false
```
### Cache Management
```bash
# Clear Metro cache
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
# Clear watchman
watchman watch-del-all
# Clear all (comprehensive)
npm run clear # Custom script
# Or manually:
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
watchman watch-del-all
rm -rf node_modules
npm install
```
## Pro Tips & Tricks
### 1. Bundle Analysis
Analyze bundle size to find optimization opportunities:
```bash
# Generate bundle with source map
npx react-native bundle \
--platform ios \
--dev false \
--entry-file index.js \
--bundle-output ./bundle.js \
--sourcemap-output ./bundle.map
# Analyze with source-map-explorer
npm install -g source-map-explorer
source-map-explorer bundle.js bundle.map
```
### 2. Environment-Specific Configuration
```javascript
// metro.config.js
const isDev = process.env.NODE_ENV !== 'production';
module.exports = {
transformer: {
minifierConfig: {
compress: {
drop_console: !isDev, // Remove console.log in production
},
},
},
serializer: {
getModulesRunBeforeMainModule: () => [
// Polyfills for production
...(!isDev ? [require.resolve('./polyfills.js')] : []),
],
},
};
```
### 3. Custom Asset Pipeline
```javascript
// metro.config.js
module.exports = {
transformer: {
// Optimize images during bundling
assetPlugins: ['expo-asset/tools/hashAssetFiles'],
},
resolver: {
assetExts: ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'],
// Custom asset resolution
resolveAsset: (dirPath, assetName, extension) => {
const basePath = `${dirPath}/${assetName}`;
// Try @2x, @3x variants
const variants = ['@3x', '@2x', ''];
for (const variant of variants) {
const path = `${basePath}${variant}.${extension}`;
if (require('fs').existsSync(path)) {
return path;
}
}
return null;
},
},
};
```
### 4. Preloading Heavy Modules
```javascript
// index.js
import { AppRegistry } from 'react-native';
import App from './App';
// Preload heavy modules
import('./src/heavyModule').then(() => {
console.log('Heavy module preloaded');
});
AppRegistry.registerComponent('MyApp', () => App);
```
### 5. Development Performance Boost
```javascript
// metro.config.js
const isDev = process.env.NODE_ENV !== 'production';
module.exports = {
transformer: {
// Skip minification in dev
minifierPath: isDev ? undefined : require.resolve('metro-minify-terser'),
// Faster source maps in dev
getTransformOptions: async () => ({
transform: {
inlineRequires: !isDev, // Only in production
},
}),
},
server: {
// Increase file watching performance
watchFolders: isDev ? [] : undefined,
},
};
```
## Integration with SpecWeave
**Configuration Management**
- Document Metro configuration in `docs/internal/architecture/`
- Track bundle size across increments
- Include bundling optimization in `tasks.md`
**Performance Monitoring**
- Set bundle size thresholds
- Track startup time improvements
- Document optimization strategies
**Troubleshooting**
- Maintain runbook for common Metro issues
- Document cache clearing procedures
- Track bundling errors in increment reports

536
skills/mobile-debugging/SKILL.md Normal file
View File

@@ -0,0 +1,536 @@
---
name: mobile-debugging
description: Expert in debugging React Native and Expo mobile applications. Covers React DevTools, Flipper, Chrome DevTools, network debugging, crash analysis, error boundaries, debugging native modules, remote debugging, breakpoints, console logging strategies. Activates for debugging mobile app, react native debugging, flipper, devtools, breakpoints, crash, error, remote debugging, network request debugging, console.log, debugger, react native debugger.
---
# Mobile Debugging Expert
Specialized in debugging React Native and Expo applications across iOS and Android platforms. Expert in using debugging tools, analyzing crashes, network debugging, and troubleshooting common React Native issues.
## What I Know
### Debugging Tools
**React DevTools**
- Component tree inspection
- Props and state inspection
- Profiler for performance analysis
- Component re-render tracking
- Installation: `npm install -g react-devtools`
- Usage: `react-devtools` before starting app
**Chrome DevTools (Remote Debugging)**
- JavaScript debugger access
- Breakpoints and step-through debugging
- Console for logging and evaluation
- Network tab for API inspection
- Source maps for original code navigation
**Flipper (Meta's Debugging Platform)**
- Layout inspector for UI debugging
- Network inspector with request/response details
- Logs viewer with filtering
- React DevTools plugin integration
- Database inspector
- Crash reporter integration
- Performance metrics monitoring
**React Native Debugger (Standalone)**
- All-in-one debugging solution
- Redux DevTools integration
- React DevTools integration
- Network inspection
- AsyncStorage inspection
### Debugging Techniques
**Console Logging Strategies**
```javascript
// Basic logging
console.log('Debug:', value);
// Structured logging
console.log({
component: 'UserProfile',
action: 'loadData',
userId: user.id,
timestamp: new Date().toISOString()
});
// Conditional logging
if (__DEV__) {
console.log('Development only:', debugData);
}
// Performance logging
console.time('DataLoad');
await fetchData();
console.timeEnd('DataLoad');
// Table logging for arrays
console.table(users);
```
**Breakpoint Debugging**
```javascript
// Debugger statement
function processData(data) {
debugger; // Execution pauses here when debugger attached
return data.map(item => transform(item));
}
// Conditional breakpoints in DevTools
// Right-click on line number → Add conditional breakpoint
// Condition: userId === '12345'
```
**Error Boundaries**
```javascript
import React from 'react';
import { View, Text } from 'react-native';
class ErrorBoundary extends React.Component {
state = { hasError: false, error: null };
static getDerivedStateFromError(error) {
return { hasError: true, error };
}
componentDidCatch(error, errorInfo) {
// Log to error tracking service
console.error('Error caught:', error, errorInfo);
logErrorToService(error, errorInfo);
}
render() {
if (this.state.hasError) {
return (
<View>
<Text>Something went wrong.</Text>
<Text>{this.state.error?.message}</Text>
</View>
);
}
return this.props.children;
}
}
// Usage
<ErrorBoundary>
<App />
</ErrorBoundary>
```
### Network Debugging
**Intercepting Network Requests**
```javascript
// Using Flipper (recommended)
// Automatically intercepts fetch() and XMLHttpRequest
// Manual interception for custom debugging
const originalFetch = global.fetch;
global.fetch = async (...args) => {
console.log('Fetch Request:', args[0], args[1]);
const response = await originalFetch(...args);
console.log('Fetch Response:', response.status);
return response;
};
// Using React Native Debugger Network tab
// Automatically works with fetch() and axios
```
**API Response Debugging**
```javascript
// Wrapper for API calls with detailed logging
async function apiCall(endpoint, options = {}) {
const startTime = Date.now();
try {
const response = await fetch(endpoint, options);
const duration = Date.now() - startTime;
console.log({
endpoint,
method: options.method || 'GET',
status: response.status,
duration: `${duration}ms`,
success: response.ok
});
if (!response.ok) {
const error = await response.text();
console.error('API Error Response:', error);
throw new Error(`API Error: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('API Call Failed:', {
endpoint,
error: error.message,
duration: `${Date.now() - startTime}ms`
});
throw error;
}
}
```
### Platform-Specific Debugging
**iOS Debugging**
- Safari Web Inspector for JSContext debugging
- Xcode Console for native logs
- Instruments for performance profiling
- Crash logs: `~/Library/Logs/DiagnosticReports/`
- System logs: `log stream --predicate 'processImagePath contains "MyApp"'`
**Android Debugging**
- Chrome DevTools for JavaScript debugging
- Android Studio Logcat for system logs
- ADB logcat filtering: `adb logcat *:E` (errors only)
- Native crash logs: `adb logcat AndroidRuntime:E`
- Monitoring device: `adb shell top`
### Common Debugging Scenarios
**App Crashes on Startup**
```bash
# iOS: Check Xcode console
# Open Xcode → Window → Devices and Simulators → Select device → View logs
# Android: Check logcat
adb logcat *:E
# Look for:
# - Missing native modules
# - JavaScript bundle errors
# - Permission issues
# - Initialization errors
```
**White Screen / Blank Screen**
```javascript
// Add error boundary to root
import { ErrorBoundary } from 'react-error-boundary';
function ErrorFallback({ error }) {
return (
<View>
<Text>App crashed: {error.message}</Text>
</View>
);
}
<ErrorBoundary FallbackComponent={ErrorFallback}>
<App />
</ErrorBoundary>
```
**Red Screen Errors**
```javascript
// Globally catch errors in development
if (__DEV__) {
ErrorUtils.setGlobalHandler((error, isFatal) => {
console.log('Global Error:', { error, isFatal });
// Log to crash reporting service in production
});
}
```
**Network Request Failures**
```bash
# Check if Metro bundler is accessible
curl http://localhost:8081/status
# Check if API is accessible from device
# iOS Simulator: localhost works
# Android Emulator: use 10.0.2.2 instead of localhost
# Real device: use computer's IP address
# Test network connectivity
adb shell ping 8.8.8.8 # Android
```
**Performance Issues**
```javascript
// Use React DevTools Profiler
import { Profiler } from 'react';
function onRenderCallback(
id,
phase,
actualDuration,
baseDuration,
startTime,
commitTime
) {
console.log({
component: id,
phase,
actualDuration,
baseDuration
});
}
<Profiler id="App" onRender={onRenderCallback}>
<App />
</Profiler>
```
## When to Use This Skill
Ask me when you need help with:
- Setting up debugging tools (Flipper, React DevTools)
- Debugging crashes or error screens
- Inspecting network requests and responses
- Finding performance bottlenecks
- Analyzing component re-renders
- Debugging native module issues
- Reading crash logs and stack traces
- Setting up error boundaries
- Remote debugging on physical devices
- Debugging platform-specific issues
- Troubleshooting "white screen" errors
- Inspecting AsyncStorage or databases
## Essential Debugging Commands
### Start Debugging
```bash
# Open React DevTools
react-devtools
# Start app with remote debugging
npm start
# In app: Shake device → Debug Remote JS
# Or: Press "d" in Metro bundler terminal
```
### Platform Logs
```bash
# iOS System Logs (real device)
idevicesyslog
# iOS Simulator Logs
xcrun simctl spawn booted log stream --level=debug
# Android Logs (all)
adb logcat
# Android Logs (app only, errors)
adb logcat *:E | grep com.myapp
# Android Logs (React Native only)
adb logcat ReactNative:V ReactNativeJS:V *:S
# Clear Android logs
adb logcat -c
```
### Performance Analysis
```bash
# iOS: Use Instruments
# Xcode → Open Developer Tool → Instruments → Time Profiler
# Android: Use Systrace
react-native log-android
# React Native performance monitor
# Shake device → Show Perf Monitor
```
### Flipper Setup
```bash
# Install Flipper Desktop
brew install --cask flipper
# For Expo dev clients, add to app.json:
{
"expo": {
"plugins": ["react-native-flipper"]
}
}
# Rebuild dev client
eas build --profile development --platform all
```
## Pro Tips & Tricks
### 1. Custom Dev Menu
Add custom debugging tools to dev menu:
```javascript
import { DevSettings } from 'react-native';
if (__DEV__) {
DevSettings.addMenuItem('Clear AsyncStorage', async () => {
await AsyncStorage.clear();
console.log('AsyncStorage cleared');
});
DevSettings.addMenuItem('Log Redux State', () => {
console.log('Redux State:', store.getState());
});
DevSettings.addMenuItem('Toggle Debug Mode', () => {
global.DEBUG = !global.DEBUG;
console.log('Debug mode:', global.DEBUG);
});
}
```
### 2. Network Request Logger
Comprehensive network debugging:
```javascript
// Create a network logger file
import axios from 'axios';
if (__DEV__) {
axios.interceptors.request.use(
(config) => {
console.log('→ API Request', {
method: config.method?.toUpperCase(),
url: config.url,
data: config.data,
headers: config.headers
});
return config;
},
(error) => {
console.error('→ Request Error', error);
return Promise.reject(error);
}
);
axios.interceptors.response.use(
(response) => {
console.log('← API Response', {
status: response.status,
url: response.config.url,
data: response.data
});
return response;
},
(error) => {
console.error('← Response Error', {
status: error.response?.status,
url: error.config?.url,
data: error.response?.data
});
return Promise.reject(error);
}
);
}
```
### 3. React Query DevTools (for data fetching)
```javascript
import { useReactQueryDevTools } from '@tanstack/react-query-devtools';
function App() {
// Development only
if (__DEV__) {
useReactQueryDevTools();
}
return <YourApp />;
}
```
### 4. Debugging State Updates
Track state changes with custom hook:
```javascript
import { useEffect, useRef } from 'react';
function useTraceUpdate(props, componentName) {
const prev = useRef(props);
useEffect(() => {
const changedProps = Object.entries(props).reduce((acc, [key, value]) => {
if (prev.current[key] !== value) {
acc[key] = {
from: prev.current[key],
to: value
};
}
return acc;
}, {});
if (Object.keys(changedProps).length > 0) {
console.log(`[${componentName}] Changed props:`, changedProps);
}
prev.current = props;
});
}
// Usage
function MyComponent(props) {
useTraceUpdate(props, 'MyComponent');
return <View>...</View>;
}
```
### 5. Debugging Offline/Online State
```javascript
import NetInfo from '@react-native-community/netinfo';
// Monitor network state
NetInfo.addEventListener(state => {
console.log('Network State:', {
isConnected: state.isConnected,
type: state.type,
isInternetReachable: state.isInternetReachable
});
});
```
### 6. Production Error Tracking
Integrate with error tracking services:
```javascript
// Using Sentry (example)
import * as Sentry from '@sentry/react-native';
Sentry.init({
dsn: 'YOUR_SENTRY_DSN',
enableInExpoDevelopment: true,
debug: __DEV__
});
// Capture custom errors
try {
await riskyOperation();
} catch (error) {
Sentry.captureException(error, {
tags: { feature: 'user-profile' },
extra: { userId: user.id }
});
}
```
## Integration with SpecWeave
**During Development**
- Document debugging approaches in increment `reports/`
- Track known issues and workarounds in `spec.md`
- Include debugging steps in `tasks.md` test plans
**Production Monitoring**
- Set up error boundaries for all features
- Integrate crash reporting (Sentry, Bugsnag)
- Document debugging procedures in runbooks
- Track common errors in living documentation

573
skills/native-modules/SKILL.md Normal file
View File

@@ -0,0 +1,573 @@
---
name: native-modules
description: Expert in React Native native modules, bridging JavaScript and native code, writing custom native modules, using Turbo Modules, Fabric, JSI, autolinking, module configuration, iOS Swift/Objective-C modules, Android Kotlin/Java modules. Activates for native module, native code, bridge, turbo module, JSI, fabric, autolinking, custom native module, ios module, android module, swift, kotlin, objective-c, java native code.
---
# Native Modules Expert
Specialized in React Native native module integration, including custom native module development, third-party native library integration, and troubleshooting native code issues.
## What I Know
### Native Module Fundamentals
**What Are Native Modules?**
- Bridge between JavaScript and native platform code
- Access platform-specific APIs (Bluetooth, NFC, etc.)
- Performance-critical operations
- Integration with existing native SDKs
**Modern Architecture**
- **Old Architecture**: Bridge-based (React Native < 0.68)
- **New Architecture** (React Native 0.68+):
- **JSI** (JavaScript Interface): Direct JS ↔ Native communication
- **Turbo Modules**: Lazy-loaded native modules
- **Fabric**: New rendering engine
### Using Third-Party Native Modules
**Installation with Autolinking**
```bash
# Install module
npm install react-native-camera
# iOS: Install pods (autolinking handles most configuration)
cd ios && pod install && cd ..
# Rebuild the app
npm run ios
npm run android
```
**Manual Linking (Legacy)**
```bash
# React Native < 0.60 (rarely needed now)
react-native link react-native-camera
```
**Expo Integration**
```bash
# For Expo managed workflow, use config plugins
npx expo install react-native-camera
# Add plugin to app.json
{
"expo": {
"plugins": [
[
"react-native-camera",
{
"cameraPermission": "Allow $(PRODUCT_NAME) to access your camera"
}
]
]
}
}
# Rebuild dev client
eas build --profile development --platform all
```
### Creating Custom Native Modules
**iOS Native Module (Swift)**
```swift
// RCTCalendarModule.swift
import Foundation
@objc(CalendarModule)
class CalendarModule: NSObject {
@objc
static func requiresMainQueueSetup() -> Bool {
return false
}
@objc
func createEvent(_ name: String, location: String, date: NSNumber) {
// Native implementation
print("Creating event: \(name) at \(location)")
}
@objc
func getEvents(_ callback: @escaping RCTResponseSenderBlock) {
let events = ["Event 1", "Event 2", "Event 3"]
callback([NSNull(), events])
}
@objc
func findEvents(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
// Async with Promise
DispatchQueue.global().async {
let events = self.fetchEventsFromNativeAPI()
resolve(events)
}
}
}
```
```objectivec
// RCTCalendarModule.m (Bridge file)
#import <React/RCTBridgeModule.h>
@interface RCT_EXTERN_MODULE(CalendarModule, NSObject)
RCT_EXTERN_METHOD(createEvent:(NSString *)name location:(NSString *)location date:(nonnull NSNumber *)date)
RCT_EXTERN_METHOD(getEvents:(RCTResponseSenderBlock)callback)
RCT_EXTERN_METHOD(findEvents:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
@end
```
**Android Native Module (Kotlin)**
```kotlin
// CalendarModule.kt
package com.myapp
import com.facebook.react.bridge.*
class CalendarModule(reactContext: ReactApplicationContext) :
ReactContextBaseJavaModule(reactContext) {
override fun getName(): String {
return "CalendarModule"
}
@ReactMethod
fun createEvent(name: String, location: String, date: Double) {
// Native implementation
println("Creating event: $name at $location")
}
@ReactMethod
fun getEvents(callback: Callback) {
val events = WritableNativeArray().apply {
pushString("Event 1")
pushString("Event 2")
pushString("Event 3")
}
callback.invoke(null, events)
}
@ReactMethod
fun findEvents(promise: Promise) {
try {
val events = fetchEventsFromNativeAPI()
promise.resolve(events)
} catch (e: Exception) {
promise.reject("ERROR", e.message, e)
}
}
}
```
```kotlin
// CalendarPackage.kt
package com.myapp
import com.facebook.react.ReactPackage
import com.facebook.react.bridge.NativeModule
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.uimanager.ViewManager
class CalendarPackage : ReactPackage {
override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
return listOf(CalendarModule(reactContext))
}
override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
return emptyList()
}
}
```
**JavaScript Usage**
```javascript
// CalendarModule.js
import { NativeModules } from 'react-native';
const { CalendarModule } = NativeModules;
export default {
createEvent: (name, location, date) => {
CalendarModule.createEvent(name, location, date);
},
getEvents: (callback) => {
CalendarModule.getEvents((error, events) => {
if (error) {
console.error(error);
} else {
callback(events);
}
});
},
findEvents: async () => {
try {
const events = await CalendarModule.findEvents();
return events;
} catch (error) {
console.error(error);
throw error;
}
}
};
// Usage in components
import CalendarModule from './CalendarModule';
function MyComponent() {
const handleCreateEvent = () => {
CalendarModule.createEvent('Meeting', 'Office', Date.now());
};
const handleGetEvents = async () => {
const events = await CalendarModule.findEvents();
console.log('Events:', events);
};
return (
<View>
<Button title="Create Event" onPress={handleCreateEvent} />
<Button title="Get Events" onPress={handleGetEvents} />
</View>
);
}
```
### Turbo Modules (New Architecture)
**Creating a Turbo Module**
```typescript
// NativeCalendarModule.ts (Codegen spec)
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';
export interface Spec extends TurboModule {
createEvent(name: string, location: string, date: number): void;
findEvents(): Promise<string[]>;
}
export default TurboModuleRegistry.getEnforcing<Spec>('CalendarModule');
```
**Benefits of Turbo Modules**
- Lazy loading: Loaded only when used
- Type safety with TypeScript
- Faster initialization
- Better performance via JSI
### Native UI Components
**Custom Native View (iOS - Swift)**
```swift
// RCTCustomViewManager.swift
import UIKit
@objc(CustomViewManager)
class CustomViewManager: RCTViewManager {
override static func requiresMainQueueSetup() -> Bool {
return true
}
override func view() -> UIView! {
return CustomView()
}
@objc func setColor(_ view: CustomView, color: NSNumber) {
view.backgroundColor = RCTConvert.uiColor(color)
}
}
class CustomView: UIView {
override init(frame: CGRect) {
super.init(frame: frame)
self.backgroundColor = .blue
}
required init?(coder: NSCoder) {
fatalError("init(coder:) has not been implemented")
}
}
```
**Custom Native View (Android - Kotlin)**
```kotlin
// CustomViewManager.kt
class CustomViewManager : SimpleViewManager<View>() {
override fun getName(): String {
return "CustomView"
}
override fun createViewInstance(reactContext: ThemedReactContext): View {
return View(reactContext).apply {
setBackgroundColor(Color.BLUE)
}
}
@ReactProp(name = "color")
fun setColor(view: View, color: Int) {
view.setBackgroundColor(color)
}
}
```
**JavaScript Usage**
```javascript
import { requireNativeComponent } from 'react-native';
const CustomView = requireNativeComponent('CustomView');
function MyComponent() {
return (
<CustomView
style={{ width: 200, height: 200 }}
color="red"
/>
);
}
```
### Common Native Module Issues
**Module Not Found**
```bash
# iOS: Clear build and reinstall pods
cd ios && rm -rf build Pods && pod install && cd ..
npm run ios
# Android: Clean and rebuild
cd android && ./gradlew clean && cd ..
npm run android
# Clear Metro cache
npx react-native start --reset-cache
```
**Autolinking Not Working**
```bash
# Verify module in package.json
npm list react-native-camera
# Re-run pod install
cd ios && pod install && cd ..
# Check react-native.config.js for custom linking config
```
**Native Crashes**
```bash
# iOS: Check Xcode console for crash logs
# Look for:
# - Unrecognized selector sent to instance
# - Null pointer exceptions
# - Memory issues
# Android: Check logcat
adb logcat *:E
# Look for:
# - Java exceptions
# - JNI errors
# - Null pointer exceptions
```
## When to Use This Skill
Ask me when you need help with:
- Integrating third-party native modules
- Creating custom native modules
- Troubleshooting native module installation
- Writing iOS native code (Swift/Objective-C)
- Writing Android native code (Kotlin/Java)
- Debugging native crashes
- Understanding Turbo Modules and JSI
- Migrating to New Architecture
- Creating custom native UI components
- Handling platform-specific APIs
- Resolving autolinking issues
## Essential Commands
### Module Development
```bash
# Create module template
npx create-react-native-module my-module
# Build iOS module
cd ios && xcodebuild
# Build Android module
cd android && ./gradlew assembleRelease
# Test module locally
npm link
cd ../MyApp && npm link my-module
```
### Debugging Native Code
```bash
# iOS: Run with Xcode debugger
open ios/MyApp.xcworkspace
# Android: Run with Android Studio debugger
# Open android/ folder in Android Studio
# Print native logs
# iOS
tail -f ~/Library/Logs/DiagnosticReports/*.crash
# Android
adb logcat | grep "CalendarModule"
```
## Pro Tips & Tricks
### 1. Type-Safe Native Modules with Codegen
Use Codegen (New Architecture) for type safety:
```typescript
// NativeMyModule.ts
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';
export interface Spec extends TurboModule {
getString(key: string): Promise<string>;
setString(key: string, value: string): void;
}
export default TurboModuleRegistry.getEnforcing<Spec>('MyModule');
```
### 2. Event Emitters for Native → JS Communication
```swift
// iOS - Emit events to JavaScript
import Foundation
@objc(DeviceOrientationModule)
class DeviceOrientationModule: RCTEventEmitter {
override func supportedEvents() -> [String]! {
return ["OrientationChanged"]
}
@objc
override static func requiresMainQueueSetup() -> Bool {
return true
}
@objc
func startObserving() {
NotificationCenter.default.addObserver(
self,
selector: #selector(orientationChanged),
name: UIDevice.orientationDidChangeNotification,
object: nil
)
}
@objc
func stopObserving() {
NotificationCenter.default.removeObserver(self)
}
@objc
func orientationChanged() {
let orientation = UIDevice.current.orientation
sendEvent(withName: "OrientationChanged", body: ["orientation": orientation.rawValue])
}
}
```
```javascript
// JavaScript - Listen to native events
import { NativeEventEmitter, NativeModules } from 'react-native';
const { DeviceOrientationModule } = NativeModules;
const eventEmitter = new NativeEventEmitter(DeviceOrientationModule);
function MyComponent() {
useEffect(() => {
const subscription = eventEmitter.addListener('OrientationChanged', (data) => {
console.log('Orientation:', data.orientation);
});
return () => subscription.remove();
}, []);
return <View />;
}
```
### 3. Native Module with Callbacks
```kotlin
// Android - Pass callbacks
@ReactMethod
fun processData(data: String, successCallback: Callback, errorCallback: Callback) {
try {
val result = heavyProcessing(data)
successCallback.invoke(result)
} catch (e: Exception) {
errorCallback.invoke(e.message)
}
}
```
```javascript
// JavaScript
CalendarModule.processData(
'input data',
(result) => console.log('Success:', result),
(error) => console.error('Error:', error)
);
```
### 4. Synchronous Native Methods (Use Sparingly)
```swift
// iOS - Synchronous method (blocks JS thread!)
@objc
func getDeviceId() -> String {
return UIDevice.current.identifierForVendor?.uuidString ?? "unknown"
}
```
```javascript
// JavaScript - Synchronous call
const deviceId = CalendarModule.getDeviceId();
console.log(deviceId); // Returns immediately
```
**Warning**: Synchronous methods block the JS thread. Use only for very fast operations (<5ms).
## Integration with SpecWeave
**Native Module Planning**
- Document native dependencies in `spec.md`
- Include native module setup in `plan.md`
- Add native code compilation to `tasks.md`
**Testing Strategy**
- Unit test native code separately
- Integration test JS ↔ Native bridge
- Test on both iOS and Android
- Document platform-specific behaviors
**Documentation**
- Maintain native module API documentation
- Document platform-specific quirks
- Keep runbooks for common native issues

550
skills/performance-optimization/SKILL.md Normal file
View File

@@ -0,0 +1,550 @@
---
name: performance-optimization
description: Expert in React Native performance optimization including bundle size reduction, memory management, rendering optimization, image optimization, list performance, navigation optimization, startup time, FlatList, memoization, React.memo, useMemo, useCallback, lazy loading, code splitting. Activates for performance, slow app, lag, memory leak, bundle size, optimization, flatlist performance, re-render, fps, jank, startup time, app size.
---
# Performance Optimization Expert
Specialized in optimizing React Native and Expo applications for production. Expert in reducing bundle size, improving render performance, optimizing memory usage, and eliminating jank.
## What I Know
### Bundle Size Optimization
**Analyzing Bundle Size**
```bash
# Generate bundle stats (Expo)
npx expo export --dump-sourcemap
# Analyze with source-map-explorer
npx source-map-explorer bundles/**/*.map
# Check production bundle size
npx expo export --platform ios
du -sh dist/
# Metro bundle visualizer
npx react-native-bundle-visualizer
```
**Reducing Bundle Size**
- Remove unused dependencies
- Use Hermes engine (Android)
- Enable code minification and obfuscation
- Tree shaking for unused code elimination
- Lazy load heavy screens and components
- Optimize asset sizes (images, fonts)
**Hermes Configuration**
```javascript
// app.json (Expo)
{
"expo": {
"jsEngine": "hermes", // Faster startup, smaller bundle
"ios": {
"jsEngine": "hermes"
},
"android": {
"jsEngine": "hermes"
}
}
}
```
### Rendering Performance
**React.memo for Component Optimization**
```javascript
import React, { memo } from 'react';
// Without memo: Re-renders on every parent render
const UserCard = ({ user }) => (
<View>
<Text>{user.name}</Text>
</View>
);
// With memo: Only re-renders when user prop changes
const UserCard = memo(({ user }) => (
<View>
<Text>{user.name}</Text>
</View>
));
// Custom comparison function
const UserCard = memo(
({ user }) => <View><Text>{user.name}</Text></View>,
(prevProps, nextProps) => prevProps.user.id === nextProps.user.id
);
```
**useMemo and useCallback**
```javascript
import { useMemo, useCallback } from 'react';
function UserList({ users, onUserPress }) {
// Expensive calculation - only recalculates when users changes
const sortedUsers = useMemo(() => {
console.log('Sorting users...');
return users.sort((a, b) => a.name.localeCompare(b.name));
}, [users]);
// Stable callback reference - prevents child re-renders
const handlePress = useCallback((userId) => {
console.log('User pressed:', userId);
onUserPress(userId);
}, [onUserPress]);
return (
<FlatList
data={sortedUsers}
renderItem={({ item }) => (
<UserItem user={item} onPress={handlePress} />
)}
keyExtractor={item => item.id}
/>
);
}
```
**Avoiding Inline Functions and Objects**
```javascript
// ❌ BAD: Creates new function on every render
<TouchableOpacity onPress={() => handlePress(item.id)}>
<Text style={{ color: 'blue' }}>Press</Text>
</TouchableOpacity>
// ✅ GOOD: Stable references
const styles = StyleSheet.create({
buttonText: { color: 'blue' }
});
const handleItemPress = useCallback(() => {
handlePress(item.id);
}, [item.id]);
<TouchableOpacity onPress={handleItemPress}>
<Text style={styles.buttonText}>Press</Text>
</TouchableOpacity>
```
### List Performance (FlatList/SectionList)
**Optimized FlatList Configuration**
```javascript
import { FlatList } from 'react-native';
function OptimizedList({ data }) {
const renderItem = useCallback(({ item }) => (
<UserCard user={item} />
), []);
const keyExtractor = useCallback((item) => item.id, []);
return (
<FlatList
data={data}
renderItem={renderItem}
keyExtractor={keyExtractor}
// Performance optimizations
initialNumToRender={10} // Render 10 items initially
maxToRenderPerBatch={10} // Render 10 items per batch
windowSize={5} // Keep 5 screens worth of items
removeClippedSubviews={true} // Unmount off-screen items
updateCellsBatchingPeriod={50} // Batch updates every 50ms
// Memoization
getItemLayout={getItemLayout} // For fixed-height items
// Optional: Performance monitor
onEndReachedThreshold={0.5} // Load more at 50% scroll
onEndReached={loadMoreData}
/>
);
}
// For fixed-height items (huge performance boost)
const ITEM_HEIGHT = 80;
const getItemLayout = (data, index) => ({
length: ITEM_HEIGHT,
offset: ITEM_HEIGHT * index,
index,
});
```
**FlashList (Better than FlatList)**
```javascript
// Install: npm install @shopify/flash-list
import { FlashList } from "@shopify/flash-list";
function SuperFastList({ data }) {
return (
<FlashList
data={data}
renderItem={({ item }) => <UserCard user={item} />}
estimatedItemSize={80} // Required: approximate item height
/>
);
}
```
### Image Optimization
**Fast Image for Better Performance**
```javascript
// Install: npm install react-native-fast-image
import FastImage from 'react-native-fast-image';
function ProfilePicture({ uri }) {
return (
<FastImage
style={{ width: 100, height: 100 }}
source={{
uri: uri,
priority: FastImage.priority.normal, // high, normal, low
cache: FastImage.cacheControl.immutable // Aggressive caching
}}
resizeMode={FastImage.resizeMode.cover}
/>
);
}
```
**Image Optimization Best Practices**
```javascript
// Use appropriate sizes (not 4K images for thumbnails)
<Image
source={{ uri: 'https://example.com/image.jpg?w=200&h=200' }}
style={{ width: 100, height: 100 }}
/>
// Use local images when possible (bundled)
<Image source={require('./assets/logo.png')} />
// Progressive loading
import { Image } from 'react-native';
<Image
source={{ uri: imageUrl }}
defaultSource={require('./placeholder.png')} // iOS only
style={{ width: 200, height: 200 }}
/>
```
### Memory Management
**Preventing Memory Leaks**
```javascript
import { useEffect } from 'react';
function Component() {
useEffect(() => {
// Set up subscription
const subscription = api.subscribe(data => {
console.log(data);
});
// Clean up on unmount (CRITICAL!)
return () => {
subscription.unsubscribe();
};
}, []);
// Timers
useEffect(() => {
const timer = setInterval(() => {
console.log('Tick');
}, 1000);
return () => clearInterval(timer); // Clean up timer
}, []);
}
```
**Image Memory Management**
```javascript
// Clear image cache when memory warning
import { Platform, Image } from 'react-native';
import FastImage from 'react-native-fast-image';
if (Platform.OS === 'ios') {
// iOS: Clear cache on memory warning
DeviceEventEmitter.addListener('RCTMemoryWarning', () => {
FastImage.clearMemoryCache();
});
}
// Manual cache clearing
FastImage.clearMemoryCache();
FastImage.clearDiskCache();
```
### Navigation Performance
**Lazy Loading Screens**
```javascript
import { lazy, Suspense } from 'react';
import { ActivityIndicator } from 'react-native';
// Lazy load heavy screens
const ProfileScreen = lazy(() => import('./screens/ProfileScreen'));
const SettingsScreen = lazy(() => import('./screens/SettingsScreen'));
function App() {
return (
<Suspense fallback={<ActivityIndicator />}>
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen name="Profile" component={ProfileScreen} />
<Stack.Screen name="Settings" component={SettingsScreen} />
</Stack.Navigator>
</NavigationContainer>
</Suspense>
);
}
```
**React Navigation Optimization**
```javascript
// Freeze inactive screens (React Navigation v6+)
import { enableScreens } from 'react-native-screens';
enableScreens();
// Detach inactive screens
<Stack.Navigator
screenOptions={{
detachPreviousScreen: true, // Unmount inactive screens
}}
>
<Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>
```
### Startup Time Optimization
**Reducing Initial Load Time**
```javascript
// app.json - Optimize splash screen
{
"expo": {
"splash": {
"image": "./assets/splash.png",
"resizeMode": "contain",
"backgroundColor": "#ffffff"
}
}
}
// Use Hermes for faster startup
{
"expo": {
"jsEngine": "hermes"
}
}
```
**Defer Non-Critical Initialization**
```javascript
import { InteractionManager } from 'react-native';
function App() {
useEffect(() => {
// Critical initialization
initializeAuth();
// Defer non-critical tasks until after animations
InteractionManager.runAfterInteractions(() => {
initializeAnalytics();
initializeCrashReporting();
preloadImages();
});
}, []);
return <AppContent />;
}
```
### Animation Performance
**Use Native Driver**
```javascript
import { Animated } from 'react-native';
function FadeInView({ children }) {
const opacity = useRef(new Animated.Value(0)).current;
useEffect(() => {
Animated.timing(opacity, {
toValue: 1,
duration: 300,
useNativeDriver: true, // Runs on native thread (60fps)
}).start();
}, []);
return (
<Animated.View style={{ opacity }}>
{children}
</Animated.View>
);
}
```
**Reanimated for Complex Animations**
```javascript
// Install: npm install react-native-reanimated
import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
function DraggableBox() {
const offset = useSharedValue(0);
const animatedStyle = useAnimatedStyle(() => ({
transform: [{ translateX: offset.value }],
}));
const handlePress = () => {
offset.value = withSpring(offset.value + 50);
};
return (
<Animated.View style={[styles.box, animatedStyle]}>
<Text>Drag me</Text>
</Animated.View>
);
}
```
## When to Use This Skill
Ask me when you need help with:
- Reducing app bundle size
- Optimizing FlatList/SectionList performance
- Fixing memory leaks
- Improving app startup time
- Eliminating jank and frame drops
- Optimizing image loading and caching
- Reducing component re-renders
- Implementing lazy loading
- Optimizing navigation performance
- Analyzing performance bottlenecks
- Using React.memo, useMemo, useCallback effectively
- Implementing 60fps animations
## Performance Monitoring
### React Native Performance Monitor
```javascript
// In app, shake device → Show Perf Monitor
// Shows:
// - JS frame rate
// - UI frame rate
// - RAM usage
```
### Production Performance Monitoring
```javascript
// Install: npm install @react-native-firebase/perf
import perf from '@react-native-firebase/perf';
// Custom trace
const trace = await perf().startTrace('user_profile_load');
await loadUserProfile();
await trace.stop();
// HTTP monitoring (automatic with Firebase)
import '@react-native-firebase/perf/lib/modular/index';
```
## Pro Tips & Tricks
### 1. Profile with React DevTools Profiler
```javascript
import { Profiler } from 'react';
function onRender(id, phase, actualDuration) {
if (actualDuration > 16) { // Slower than 60fps
console.warn(`Slow render in ${id}: ${actualDuration}ms`);
}
}
<Profiler id="UserList" onRender={onRender}>
<UserList users={users} />
</Profiler>
```
### 2. Debounce Expensive Operations
```javascript
import { debounce } from 'lodash';
import { useCallback } from 'react';
function SearchScreen() {
const debouncedSearch = useCallback(
debounce((query) => {
performSearch(query);
}, 300),
[]
);
return (
<TextInput
onChangeText={debouncedSearch}
placeholder="Search..."
/>
);
}
```
### 3. Virtualize Long Lists
Use FlashList or RecyclerListView instead of ScrollView with many items:
```javascript
// ❌ BAD: Renders all 1000 items
<ScrollView>
{items.map(item => <ItemCard key={item.id} item={item} />)}
</ScrollView>
// ✅ GOOD: Only renders visible items
<FlashList
data={items}
renderItem={({ item }) => <ItemCard item={item} />}
estimatedItemSize={100}
/>
```
### 4. Optimize StyleSheets
```javascript
// ❌ BAD: Creates new style object on every render
<View style={{ backgroundColor: 'red', padding: 10 }} />
// ✅ GOOD: Reuses style object
const styles = StyleSheet.create({
container: {
backgroundColor: 'red',
padding: 10
}
});
<View style={styles.container} />
```
## Integration with SpecWeave
**Performance Requirements**
- Document performance targets in `spec.md` (e.g., <2s startup)
- Include performance testing in `tasks.md` test plans
- Measure before/after optimization in increment reports
**Performance Metrics**
- Bundle size: Track in increment completion reports
- Startup time: Measure and document improvements
- FPS: Target 60fps for critical UI interactions
- Memory usage: Set thresholds and monitor
**Living Documentation**
- Document performance optimization strategies
- Track bundle size trends across increments
- Maintain performance runbooks for common issues

216
skills/react-native-setup/SKILL.md Normal file
View File

@@ -0,0 +1,216 @@
---
name: react-native-setup
description: Expert in React Native environment setup and configuration. Helps with Node.js, Xcode, Android Studio, watchman installation, CocoaPods, simulators, emulators, and troubleshooting setup issues. Activates for environment setup, installation issues, xcode setup, android studio, simulators, emulators, react-native init, expo init, development environment, SDK configuration.
---
# React Native Setup Expert
Expert in React Native and Expo environment configuration across macOS, Windows, and Linux. Specializes in troubleshooting installation issues, SDK configuration, and development environment optimization.
## What I Know
### Prerequisites & Installation
**Node.js & npm**
- Node.js 18.x or later required
- Version verification: `node --version && npm --version`
- Troubleshooting Node.js installation issues
- npm vs yarn vs pnpm for React Native projects
**Xcode (macOS - iOS Development)**
- Xcode 15.x or later required
- Command line tools installation: `xcode-select --install`
- License acceptance: `sudo xcodebuild -license accept`
- Platform installation verification
- Common Xcode errors and fixes
**Android Studio (Android Development)**
- Android Studio Hedgehog or later
- Required SDK components:
- Android SDK Platform 34 or later
- Android SDK Build-Tools
- Android Emulator
- Android SDK Platform-Tools
- ANDROID_HOME environment variable setup
- SDK Manager configuration
- Common Android Studio issues
**Watchman**
- Installation via Homebrew (macOS): `brew install watchman`
- Purpose: File watching for fast refresh
- Troubleshooting watchman errors
- Cache clearing strategies
### Environment Configuration
**iOS Setup**
- CocoaPods installation and troubleshooting
- Pod install issues and resolutions
- Xcode project configuration
- Provisioning profiles and certificates
- iOS Simulator management
- Device selection: `xcrun simctl list devices`
**Android Setup**
- Gradle configuration
- Android SDK path configuration
- Environment variables (ANDROID_HOME, PATH)
- AVD (Android Virtual Device) creation
- Emulator performance optimization
- ADB troubleshooting
**Metro Bundler**
- Port 8081 configuration
- Cache clearing: `npx react-native start --reset-cache`
- Custom Metro config
- Asset resolution issues
### Common Setup Issues
**"Command not found" Errors**
- PATH configuration
- Shell profile updates (.zshrc, .bash_profile)
- Symlink issues
**SDK Not Found**
- SDK path verification
- Environment variable troubleshooting
- SDK Manager reinstallation
**Pod Install Failures**
- CocoaPods version issues
- Ffi gem compilation errors
- Ruby version compatibility
- `pod deintegrate && pod install` strategy
**Build Failures**
- Clean build strategies
- Dependency conflicts
- Native module compilation errors
- Xcode derived data clearing
## When to Use This Skill
Ask me when you need help with:
- Initial React Native environment setup
- Installing and configuring Xcode or Android Studio
- Setting up iOS simulators or Android emulators
- Troubleshooting "Command not found" errors
- Resolving SDK path or ANDROID_HOME issues
- Fixing CocoaPods installation problems
- Clearing Metro bundler cache
- Configuring development environment variables
- Troubleshooting build failures
- Setting up watchman for file watching
- Verifying development environment prerequisites
## Quick Setup Commands
### iOS (macOS)
```bash
# Install Xcode command line tools
xcode-select --install
# Accept Xcode license
sudo xcodebuild -license accept
# Install CocoaPods
sudo gem install cocoapods
# Install watchman
brew install watchman
# Verify setup
xcodebuild -version
pod --version
watchman version
```
### Android (All Platforms)
```bash
# Verify Android setup
echo $ANDROID_HOME
adb --version
emulator -version
# List available emulators
emulator -list-avds
# List connected devices
adb devices
```
### React Native Project
```bash
# Create new React Native project
npx react-native init MyProject
# Navigate to project
cd MyProject
# Install iOS dependencies
cd ios && pod install && cd ..
# Start Metro bundler
npm start
# Run on iOS (separate terminal)
npm run ios
# Run on Android (separate terminal)
npm run android
```
## Pro Tips
1. **Clean Builds**: When in doubt, clean everything
```bash
# iOS
cd ios && rm -rf build Pods && pod install && cd ..
# Android
cd android && ./gradlew clean && cd ..
# Metro
npx react-native start --reset-cache
```
2. **Environment Variables**: Always verify environment variables after changes
```bash
# Add to ~/.zshrc or ~/.bash_profile
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
# Reload shell
source ~/.zshrc
```
3. **Simulator Management**: List and boot specific devices
```bash
# iOS
xcrun simctl list devices
xcrun simctl boot "iPhone 15 Pro"
# Android
emulator -list-avds
emulator -avd Pixel_6_API_34
```
4. **Quick Health Check**: Verify entire environment
```bash
node --version # Node.js
npm --version # npm
xcodebuild -version # Xcode (macOS)
pod --version # CocoaPods (macOS)
adb --version # Android tools
watchman version # Watchman
```
## Integration with SpecWeave
This skill integrates with SpecWeave's increment workflow:
- Use during `/specweave:increment` planning for environment setup tasks
- Reference in `tasks.md` for setup-related acceptance criteria
- Include in `spec.md` for mobile-specific prerequisites
- Document setup issues in increment `reports/` folder