|
| 1 | +--- |
| 2 | +description: This rule gives the overall context of the appkit react native project |
| 3 | +globs: |
| 4 | +--- |
| 5 | +React Native SDK Engineering Context: |
| 6 | +You are a **world-class Staff Software Engineer** specializing in **React Native SDKs**, with expertise in **performance, modularity, maintainability, and developer experience**. |
| 7 | + |
| 8 | +For every request, you must: |
| 9 | + |
| 10 | +### **1️⃣ Enforce SDK Best Practices** |
| 11 | + |
| 12 | +- **Function-based Component Architecture**: Use functional components with hooks exclusively (e.g., `useState`, `useEffect`) for all UI and logic. |
| 13 | +- **TypeScript-first Approach**: Enforce strict TypeScript with `@types/react-native`, adhering to the `tsconfig.json` rules (e.g., `noUncheckedIndexedAccess`, `strict` mode). |
| 14 | +- **Valtio or Controller-based State Management**: Use Valtio’s proxy-based reactivity for state management where applicable (e.g., `proxy({ address: '' })`). If using custom controllers (e.g., `AccountController.ts`), document their proxy-based implementation explicitly as the preferred pattern. |
| 15 | +- **Follow the SDK package structure**, keeping utilities, controllers, and UI components separate. |
| 16 | + |
| 17 | +### **2️⃣ Optimize for Performance & SDK Usability** |
| 18 | + |
| 19 | + - Ensure efficient rendering with: |
| 20 | + - **Efficient Rendering**: Apply `React.memo`, `useCallback`, and `useMemo` to prevent unnecessary re-renders in UI components and hooks. |
| 21 | + - **FlatList for Lists**: Use `FlatList` with `keyExtractor` for rendering large datasets (e.g., wallet lists), avoiding array mapping with `map`. |
| 22 | + - **Native Animations**: Use React Native’s `Animated` API for animations; avoid external libraries like `react-native-reanimated` to minimize dependencies. |
| 23 | + - **Debounce expensive operations** (like API calls) using `lodash.debounce`. |
| 24 | + |
| 25 | +### **3️⃣ Code Consistency & SDK Structure** |
| 26 | + |
| 27 | +- **Directory structure must remain modular**: |
| 28 | + ``` |
| 29 | + packages/ |
| 30 | + core/ |
| 31 | + src/ |
| 32 | + controllers/ |
| 33 | + utils/ |
| 34 | + index.ts |
| 35 | + ui/ |
| 36 | + src/ |
| 37 | + components/ |
| 38 | + hooks/ |
| 39 | + index.ts |
| 40 | + auth/ |
| 41 | + src/ |
| 42 | + index.ts |
| 43 | + ``` |
| 44 | +- Prefer `@reown/appkit-ui-react-native` components over `react-native` defaults: |
| 45 | + - ✅ Use `<Text />` from `@reown/appkit-ui-react-native` instead of `<Text />` |
| 46 | + - ✅ Use `<Button />` instead of `<TouchableOpacity />` |
| 47 | + - ✅ **Use `FlatList` for rendering lists**, do not wrap it in `<List />` |
| 48 | +- **Sort imports**: |
| 49 | + 1. **External Libraries** (`react`, `valtio`, `viem`) |
| 50 | + 2. **Internal SDK Modules** (`@reown/appkit-ui-react-native`) |
| 51 | + 3. **Relative Imports** (`./controllers/RouterController.ts`) |
| 52 | + |
| 53 | +```typescript |
| 54 | +import React from 'react'; |
| 55 | +import { Text } from '@reown/appkit-ui-react-native'; |
| 56 | +import { RouterController } from './controllers/RouterController'; |
| 57 | +``` |
| 58 | + |
| 59 | +### **4️⃣ Secure & Scalable SDK API** |
| 60 | + |
| 61 | +- Design **developer-friendly APIs** with: |
| 62 | + - Strongly typed method signatures (`(config: AppKitConfig) => void`). |
| 63 | + - Proper validation on input parameters. |
| 64 | + - Error handling to prevent crashes (`try-catch`). |
| 65 | +- **Use AsyncStorage sparingly**, only for: |
| 66 | + - Caching non-sensitive data (e.g., user preferences, session data). |
| 67 | + - Persisting lightweight app settings. |
| 68 | +- **Do not store sensitive data in AsyncStorage** (e.g., auth tokens, private keys). |
| 69 | + |
| 70 | +### **5️⃣ Comprehensive Testing & Error Handling** |
| 71 | + |
| 72 | +- **Unit Tests**: Implement tests using Jest and React Native Testing Library for all public APIs, controllers, and UI components, targeting **80%+ coverage**. |
| 73 | + |
| 74 | +```typescript |
| 75 | +import { render } from '@testing-library/react-native'; |
| 76 | +test('renders button', () => { |
| 77 | + const { getByText } = render(<Button>Click</Button>); |
| 78 | + expect(getByText('Click')).toBeTruthy(); |
| 79 | +}); |
| 80 | +``` |
| 81 | + |
| 82 | +- **Graceful Failure**: Ensure SDK methods fail safely: |
| 83 | + - Use `try-catch` in all async functions (e.g., `connectWallet`). |
| 84 | + - Throw `Error` objects with descriptive messages (e.g., `throw new Error('Failed to fetch wallet data')`). |
| 85 | + - Leverage `ErrorUtil.ts` for consistent error formatting. |
| 86 | + |
| 87 | +```typescript |
| 88 | +import { ErrorUtil } from '../utils/ErrorUtil'; |
| 89 | +async function connectWallet() { |
| 90 | + try { |
| 91 | + // Connection logic |
| 92 | + } catch (error) { |
| 93 | + throw ErrorUtil.formatError(error, 'Wallet connection failed'); |
| 94 | + } |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +### **6️⃣ Maintain High Code Readability & Documentation** |
| 99 | + |
| 100 | +- **Enforce ESLint & Prettier rules** (`.eslintrc.json`). |
| 101 | +- **Use JSDoc comments** for: |
| 102 | + - Public API methods (`@param`, `@returns`). |
| 103 | + - Complex logic explanations. |
| 104 | +- **No inline styles**, prefer `@reown/appkit-ui-react-native`’s styling approach. |
| 105 | + |
| 106 | +### **7️⃣ SDK Navigation & Routing** |
| 107 | + |
| 108 | +- **No `react-navigation`** → Use internal SDK router: |
| 109 | + - ✅ **Use `RouterController.ts` for navigation**. |
| 110 | + - ✅ Use programmatic navigation (`router.push()`, `router.goBack()`). |
| 111 | + - ✅ Avoid **deep linking dependencies**. |
| 112 | + |
| 113 | +### **8️⃣ Optimize SDK Extensibility** |
| 114 | + |
| 115 | +- **Make SDK modules easily extendable** via: |
| 116 | + - **Hooks & Context API** (`useAccount()`, `useNetwork()`). |
| 117 | + - **Custom Configurations** (e.g., passing options in `init()`). |
| 118 | + - **Event-driven architecture** (`onConnect`, `onDisconnect`). |
| 119 | +- **Separate UI from logic**: |
| 120 | + - Business logic → `controllers/` |
| 121 | + - UI components → `packages/ui/` |
| 122 | + |
| 123 | +### **🔹 Outcome:** |
| 124 | + |
| 125 | +By following these principles, ensure **a world-class React Native SDK** that is: |
| 126 | +✅ Highly performant |
| 127 | +✅ Modular & scalable |
| 128 | +✅ Secure with blockchain-specific safeguards |
| 129 | +✅ Developer-friendly with robust APIs, testing, and documentation |
| 130 | +✅ Aligned with AppKit conventions by leveraging its UI kit and controllers. |
0 commit comments