Skip to content

Commit 404e053

Browse files
ignaciosantiseignaciosantise
authored
Merge pull request #524 from reown-com/agents-md-setup
docs: add AGENTS.md and CLAUDE.md SDK documentation
2 parents 1af79f2 + 36db6f7 commit 404e053

File tree

2 files changed

+303
-0
lines changed

2 files changed

+303
-0
lines changed

‎AGENTS.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# AppKit React Native SDK
2+
3+
## SDK Overview
4+
5+
**AppKit React Native** is a multichain web3 library by Reown that enables React Native applications to connect users with cryptocurrency wallets and interact with blockchain networks.
6+
7+
### Core Functionality
8+
9+
- **Wallet Connection**: Multi-wallet support via WalletConnect protocol and custom connectors (Coinbase, Phantom, etc.)
10+
- **Multichain Support**: EVM (Ethereum, Polygon, Arbitrum, etc.), Solana, and Bitcoin
11+
- **User Authentication**: Sign-In With X (SIWX) for decentralized authentication
12+
- **DeFi Features**: Token swaps, on-ramp/off-ramp, transaction monitoring
13+
- **Native Modal UI**: Pre-built, customizable React Native components
14+
- **Theme Support**: Light/dark themes with customization options
15+
16+
### Monorepo Structure
17+
18+
```
19+
packages/
20+
├── core/ # Controllers, utilities, core business logic (@reown/appkit-core-react-native)
21+
├── appkit/ # Main SDK entry point, hooks, components (@reown/appkit-react-native)
22+
├── ui/ # Reusable UI components (@reown/appkit-ui-react-native)
23+
├── common/ # Shared types, constants, utilities (@reown/appkit-common-react-native)
24+
├── ethers/ # EVM adapter using ethers.js (@reown/appkit-ethers-react-native)
25+
├── wagmi/ # EVM adapter using wagmi (@reown/appkit-wagmi-react-native)
26+
├── solana/ # Solana blockchain adapter (@reown/appkit-solana-react-native)
27+
├── bitcoin/ # Bitcoin blockchain adapter (@reown/appkit-bitcoin-react-native)
28+
├── coinbase/ # Coinbase wallet connector (@reown/appkit-coinbase-react-native)
29+
└── cli/ # CLI tools (@reown/appkit-cli-react-native)
30+
31+
apps/
32+
├── native/ # Example React Native Expo app
33+
└── gallery/ # UI component showcase
34+
```
35+
36+
### Architectural Patterns
37+
38+
**Controller Pattern (Valtio)**
39+
State management via reactive controllers:
40+
41+
- `ModalController` - Modal visibility and state
42+
- `RouterController` - Navigation between views
43+
- `ConnectionsController` - Wallet connections and networks
44+
- `SwapController` - Token swap operations
45+
- `SendController` - Transfer operations
46+
- `TransactionsController` - Transaction history
47+
48+
**Adapter Pattern**
49+
Blockchain-specific implementations:
50+
51+
- `BlockchainAdapter` - Base interface
52+
- EVM adapters (Ethers, Wagmi)
53+
- Solana adapter
54+
- Bitcoin adapter
55+
56+
**Connector Pattern**
57+
Wallet connection methods:
58+
59+
- `WalletConnectConnector` - Default WalletConnect protocol
60+
- Custom connectors for Coinbase, Phantom, etc.
61+
62+
### Tech Stack
63+
64+
- React Native 0.72+ (tested with 0.76+)
65+
- TypeScript 5.2+
66+
- Valtio (state management)
67+
- WalletConnect v2
68+
- Ethers.js / Wagmi (EVM)
69+
- Solana Web3.js
70+
71+
---
72+
73+
## UI System
74+
75+
### Package Structure
76+
77+
The UI layer is split between two packages:
78+
79+
```
80+
packages/ui/src/ # Reusable UI library (@reown/appkit-ui-react-native)
81+
├── components/ # 11 base primitives (Card, Icon, Text, Image, Modal, etc.)
82+
├── composites/ # 42 feature-rich components (Button, ListItem, InputText, etc.)
83+
├── layout/ # 3 layout helpers (FlexView, Overlay, Separator)
84+
├── context/ # ThemeContext and ThemeProvider
85+
├── hooks/ # useTheme, useAnimatedValue, useCustomDimensions
86+
├── utils/ # UiUtil, ThemeUtil, TypesUtil, TransactionUtil
87+
└── assets/ # SVG icons
88+
89+
packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native)
90+
├── modal/ # Modal wrapper and router
91+
├── views/ # Route views (Connect, Account, Swap, Networks, etc.)
92+
└── partials/ # 24 AppKit-specific composites (Header, Snackbar, QrCode, etc.)
93+
```
94+
95+
### Component Hierarchy
96+
97+
**Base Components** (`packages/ui/src/components/`):
98+
99+
- `wui-card` - Container with themed background/border
100+
- `wui-icon` - SVG icon renderer (60+ icons)
101+
- `wui-text` - Typography with 23 variants
102+
- `wui-image` - Image loader with error handling
103+
- `wui-modal` - Animated bottom sheet
104+
- `wui-pressable` - Base pressable wrapper
105+
- `wui-shimmer` - Loading skeleton
106+
- `wui-loading-spinner` - Loading indicator
107+
108+
**Composite Components** (`packages/ui/src/composites/`):
109+
110+
- `wui-button` - Primary button (size: sm/md, variant: fill/shade/accent)
111+
- `wui-list-item` - Pressable list item with animations
112+
- `wui-input-text` - Animated text input with focus states
113+
- `wui-card-select` - Wallet/Network selector card
114+
- `wui-tabs` - Animated tab switcher
115+
- `wui-qr-code` - QR code with embedded logo
116+
- `wui-snackbar` - Toast notification
117+
- `wui-avatar` - Address-based avatar with gradient
118+
119+
**Layout Components** (`packages/ui/src/layout/`):
120+
121+
- `FlexView` - Flex container replacing View (supports gap, padding arrays)
122+
- `Overlay` - Semi-transparent overlay
123+
- `Separator` - Divider with optional text
124+
125+
### Theming System
126+
127+
**Theme Colors** (62 keys in DarkTheme/LightTheme):
128+
129+
- `accent-100` to `accent-020` - Primary brand colors
130+
- `fg-100` to `fg-300` - Foreground/text colors
131+
- `bg-100` to `bg-300` - Background colors
132+
- `success-100`, `error-100` - Semantic colors
133+
- `gray-glass-001` to `gray-glass-090` - Glass morphism overlays
134+
135+
**Design Tokens**:
136+
137+
```
138+
Spacing: '0' | '4xs' | '3xs' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl'
139+
0 2 4 6 8 12 14 16 20 24 32 40 (px)
140+
141+
BorderRadius: '5xs' | '4xs' | '3xs' | 'xxs' | 'xs' | 's' | 'm' | 'l' | '3xl' | 'full'
142+
4 6 8 12 16 20 28 36 80 100 (px)
143+
```
144+
145+
**Typography** (23 variants):
146+
147+
- Sizes: `medium-title`, `small-title`, `large`, `medium`, `paragraph`, `small`, `tiny`, `micro`
148+
- Weights: `400`, `500`, `600`, `700`
149+
- Example: `paragraph-500`, `small-400`, `micro-700`
150+
151+
**Using Theme**:
152+
153+
```typescript
154+
const Theme = useTheme();
155+
// Returns themed color object that responds to light/dark mode
156+
```
157+
158+
### Animation Patterns
159+
160+
Animations use React Native's `Animated` API, preferring the native driver for GPU-accelerated properties (opacity, transforms) and falling back to `useNativeDriver: false` when animating unsupported properties like colors.
161+
162+
**Modal Animation** (native driver):
163+
164+
- Opening: Spring physics (damping: 25, stiffness: 220)
165+
- Closing: Timing animation (150ms) for snappy UX
166+
- Backdrop: Opacity fade (300ms in, 250ms out)
167+
168+
**Component Animations** (JS-driven, `useNativeDriver: false`):
169+
170+
- `useAnimatedValue` hook for color interpolation on press states
171+
- `Animated.createAnimatedComponent(Pressable)` for interactive elements
172+
- Color transitions between normal/pressed states
173+
174+
### Views and Router
175+
176+
**RouterController** manages navigation between views defined in `RouterControllerState` (see `packages/core/src/controllers/RouterController.ts` for the up-to-date list of route IDs).
177+
178+
View categories:
179+
180+
- Account flows (account overview and default account views)
181+
- Connection flows (social logins, external wallets, WalletConnect, etc.)
182+
- Network management (network selection, switching, unsupported network messaging)
183+
- On-ramp experiences (on-ramp setup, checkout, loading, settings)
184+
- Swap flows (swap entry and swap preview/review)
185+
- Wallet actions (receiving, sending, send preview/review)
186+
- Informational views (e.g., "What is a network?", "What is a wallet?")
187+
188+
**View Pattern**:
189+
190+
```typescript
191+
export function MyView() {
192+
const snapshot = useSnapshot(ControllerState);
193+
const { padding } = useCustomDimensions();
194+
195+
return (
196+
<ScrollView style={{ paddingHorizontal: padding }}>
197+
<FlexView padding={['xs', '0', 'xs', '0']}>{/* Content */}</FlexView>
198+
</ScrollView>
199+
);
200+
}
201+
```
202+
203+
### Common UI Patterns
204+
205+
**FlexView Layout**:
206+
207+
```typescript
208+
<FlexView
209+
flexDirection="row"
210+
alignItems="center"
211+
justifyContent="space-between"
212+
padding={['l', 'xl', 's', 'xl']} // [top, right, bottom, left]
213+
>
214+
```
215+
216+
**List Item**:
217+
218+
```typescript
219+
<ListItem icon="wallet" imageSrc={imageUrl} chevron onPress={handlePress} loading={isLoading}>
220+
<Text variant="paragraph-500" color="fg-100">
221+
{name}
222+
</Text>
223+
</ListItem>
224+
```
225+
226+
**Button**:
227+
228+
```typescript
229+
<Button size="md" variant="fill" onPress={handlePress}>
230+
Connect Wallet
231+
</Button>
232+
```
233+
234+
### UI Guidelines for Agents
235+
236+
1. **Use existing components** - Never create custom primitives; use the `wui-*` components
237+
2. **Follow theme system** - All colors must come from theme, no hardcoded hex values
238+
3. **Use FlexView** - Prefer FlexView over View for layout consistency
239+
4. **Spacing tokens** - Use spacing tokens ('xs', 's', 'm', etc.) not pixel values
240+
5. **Animation consistency** - Use `useAnimatedValue` hook for press state animations
241+
6. **Memoize list items** - Use `React.memo` with custom comparison for expensive list items
242+
7. **Test both themes** - Verify changes work in both light and dark mode
243+
244+
---
245+
246+
## Agent Guidance
247+
248+
### Code Quality Requirements
249+
250+
**Before pushing any solution, always run:**
251+
252+
```bash
253+
yarn format # Prettier formatting
254+
yarn lint # ESLint checks
255+
yarn test # Jest tests
256+
```
257+
258+
Follow existing code style in the codebase. Do not deviate from established patterns.
259+
260+
### Platform Compatibility
261+
262+
This SDK must work for both **Expo** and **React Native CLI** projects. Ensure any changes are compatible with both environments.
263+
264+
### Dependency Policy
265+
266+
**Keep external third-party dependencies minimal.** Avoid adding new libraries if possible - the SDK must remain lightweight. If a new dependency is absolutely necessary, justify it clearly.
267+
268+
### Key Abstractions
269+
270+
- **Adapters**: Blockchain-specific implementations (one per chain type)
271+
- **Connectors**: Wallet connection methods
272+
- **Controllers**: Valtio-based reactive state containers
273+
- **Namespaces**: CAIP-style chain identifiers (e.g., `eip155:1` for Ethereum mainnet)
274+
- **CAIP Addresses**: Chain-agnostic addresses (e.g., `eip155:1:0x...`)
275+
276+
### Important Files
277+
278+
```
279+
packages/appkit/src/AppKit.ts # Main SDK class (~900 LOC)
280+
packages/appkit/src/hooks/ # React hooks (useAppKit, useAccount, etc.)
281+
packages/core/src/controllers/ # State management controllers
282+
packages/common/src/ # Shared types and network definitions
283+
packages/ethers/src/adapter.ts # EVM adapter implementation
284+
packages/solana/src/ # Solana adapter
285+
packages/bitcoin/src/ # Bitcoin adapter
286+
```
287+
288+
### Development Commands
289+
290+
```bash
291+
yarn install # Install dependencies
292+
yarn ios # Run example on iOS simulator
293+
yarn android # Run example on Android emulator
294+
yarn build # Build all packages
295+
yarn lint # Run ESLint
296+
yarn test # Run Jest tests
297+
yarn format # Run Prettier
298+
```
299+
300+
### Commit Convention
301+
302+
Follow conventional commits: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)