diff --git a/.github/docs/development.md b/.github/docs/development.md index 6e8010874..4e43bde38 100644 --- a/.github/docs/development.md +++ b/.github/docs/development.md @@ -8,7 +8,7 @@ Install dependencies from the repository's root directory (this will also set up yarn ``` -To create your ProjectID, head to [dashboard.reown.com](https://dashboard.reown.com/) +To create your ProjectID, head to [dashboard.reown.com](https://dashboard.reown.com/). Then copy `apps/native/.env.example` to `apps/native/.env` and set `EXPO_PUBLIC_PROJECT_ID` to your ProjectID — the example app reads it from there. ## Commands diff --git a/AGENTS.md b/AGENTS.md index 76a9becc6..842d8cd7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,328 +1,111 @@ # AppKit React Native SDK -## SDK Overview +**AppKit React Native** is a multichain web3 SDK by Reown that connects React Native apps to crypto wallets and blockchains: wallet connections via the WalletConnect protocol plus custom connectors (Coinbase, Phantom, etc.), EVM / Solana / Bitcoin support, SIWX authentication, swaps, on-ramp, and a prebuilt themeable modal UI. -**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. +Tech stack: React Native 0.72+ (example app on 0.76), TypeScript 5.2, Valtio, WalletConnect v2, ethers.js / wagmi, Solana Web3.js. -### Core Functionality +Public (consumer-facing) documentation: https://docs.reown.com/appkit/react-native/core/installation — useful for checking the documented public API when changing SDK behavior. -- **Wallet Connection**: Multi-wallet support via WalletConnect protocol and custom connectors (Coinbase, Phantom, etc.) -- **Multichain Support**: EVM (Ethereum, Polygon, Arbitrum, etc.), Solana, and Bitcoin -- **User Authentication**: Sign-In With X (SIWX) for decentralized authentication -- **DeFi Features**: Token swaps, on-ramp/off-ramp, transaction monitoring -- **Native Modal UI**: Pre-built, customizable React Native components -- **Theme Support**: Light/dark themes with customization options - -### Monorepo Structure +## Monorepo Structure ``` packages/ -├── core/ # Controllers, utilities, core business logic (@reown/appkit-core-react-native) -├── appkit/ # Main SDK entry point, hooks, components (@reown/appkit-react-native) +├── core/ # Controllers, utilities, business logic (@reown/appkit-core-react-native) +├── appkit/ # Main SDK entry: hooks, modal, views, partials (@reown/appkit-react-native) ├── ui/ # Reusable UI components (@reown/appkit-ui-react-native) -├── common/ # Shared types, constants, utilities (@reown/appkit-common-react-native) -├── ethers/ # EVM adapter using ethers.js (@reown/appkit-ethers-react-native) -├── wagmi/ # EVM adapter using wagmi (@reown/appkit-wagmi-react-native) -├── solana/ # Solana blockchain adapter (@reown/appkit-solana-react-native) -├── bitcoin/ # Bitcoin blockchain adapter (@reown/appkit-bitcoin-react-native) -├── coinbase/ # Coinbase wallet connector (@reown/appkit-coinbase-react-native) -└── cli/ # CLI tools (@reown/appkit-cli-react-native) +├── common/ # Shared types, constants, network definitions (@reown/appkit-common-react-native) +├── ethers/ # EVM adapter using ethers.js +├── wagmi/ # EVM adapter using wagmi +├── solana/ # Solana adapter +├── bitcoin/ # Bitcoin adapter +├── coinbase/ # Coinbase wallet connector +└── cli/ # CLI tools apps/ -├── native/ # Example React Native Expo app -└── gallery/ # UI component showcase -``` - -### Architectural Patterns - -**Controller Pattern (Valtio)** -State management via reactive controllers: - -- `ModalController` - Modal visibility and state -- `RouterController` - Navigation between views -- `ConnectionsController` - Wallet connections and networks -- `SwapController` - Token swap operations -- `SendController` - Transfer operations -- `TransactionsController` - Transaction history - -**Adapter Pattern** -Blockchain-specific implementations: - -- `BlockchainAdapter` - Base interface -- EVM adapters (Ethers, Wagmi) -- Solana adapter -- Bitcoin adapter - -**Connector Pattern** -Wallet connection methods: - -- `WalletConnectConnector` - Default WalletConnect protocol -- Custom connectors for Coinbase, Phantom, etc. - -### Tech Stack - -- React Native 0.72+ (tested with 0.76+) -- TypeScript 5.2+ -- Valtio (state management) -- WalletConnect v2 -- Ethers.js / Wagmi (EVM) -- Solana Web3.js - ---- - -## UI System - -### Package Structure - -The UI layer is split between two packages: - -``` -packages/ui/src/ # Reusable UI library (@reown/appkit-ui-react-native) -├── components/ # 11 base primitives (Card, Icon, Text, Image, Modal, etc.) -├── composites/ # 42 feature-rich components (Button, ListItem, InputText, etc.) -├── layout/ # 3 layout helpers (FlexView, Overlay, Separator) -├── context/ # ThemeContext and ThemeProvider -├── hooks/ # useTheme, useAnimatedValue, useCustomDimensions -├── utils/ # UiUtil, ThemeUtil, TypesUtil, TransactionUtil -└── assets/ # SVG icons - -packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) -├── modal/ # Modal wrapper and router -├── views/ # Route views (Connect, Account, Swap, Networks, etc.) -└── partials/ # 24 AppKit-specific composites (Header, Snackbar, QrCode, etc.) -``` - -### Component Hierarchy +├── native/ # Example React Native Expo app (yarn ios / yarn android) +└── gallery/ # UI component showcase (Storybook) -**Base Components** (`packages/ui/src/components/`): - -- `wui-card` - Container with themed background/border -- `wui-icon` - SVG icon renderer (60+ icons) -- `wui-text` - Typography with 23 variants -- `wui-image` - Image loader with error handling -- `wui-modal` - Animated bottom sheet -- `wui-pressable` - Base pressable wrapper -- `wui-shimmer` - Loading skeleton -- `wui-loading-spinner` - Loading indicator - -**Composite Components** (`packages/ui/src/composites/`): - -- `wui-button` - Primary button (size: sm/md, variant: fill/shade/accent) -- `wui-list-item` - Pressable list item with animations -- `wui-input-text` - Animated text input with focus states -- `wui-card-select` - Wallet/Network selector card -- `wui-tabs` - Animated tab switcher -- `wui-qr-code` - QR code with embedded logo -- `wui-snackbar` - Toast notification -- `wui-avatar` - Address-based avatar with gradient - -**Layout Components** (`packages/ui/src/layout/`): - -- `FlexView` - Flex container replacing View (supports gap, padding arrays) -- `Overlay` - Semi-transparent overlay -- `Separator` - Divider with optional text - -### Theming System - -**Theme Colors** (62 keys in DarkTheme/LightTheme): - -- `accent-100` to `accent-020` - Primary brand colors -- `fg-100` to `fg-300` - Foreground/text colors -- `bg-100` to `bg-300` - Background colors -- `success-100`, `error-100` - Semantic colors -- `gray-glass-001` to `gray-glass-090` - Glass morphism overlays - -**Design Tokens**: - -``` -Spacing: '0' | '4xs' | '3xs' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' - 0 2 4 6 8 12 14 16 20 24 32 40 (px) - -BorderRadius: '5xs' | '4xs' | '3xs' | 'xxs' | 'xs' | 's' | 'm' | 'l' | '3xl' | 'full' - 4 6 8 12 16 20 28 36 80 100 (px) +examples/ +└── expo-multichain/ # Standalone npm example app — NOT part of the yarn workspace, + # so yarn build/test don't cover it. Has its own package-lock.json. ``` -**Typography** (23 variants): +## Architecture -- Sizes: `medium-title`, `small-title`, `large`, `medium`, `paragraph`, `small`, `tiny`, `micro` -- Weights: `400`, `500`, `600`, `700` -- Example: `paragraph-500`, `small-400`, `micro-700` +- **Controllers** (Valtio reactive state) in `packages/core/src/controllers/`: `ModalController`, `RouterController`, `ConnectionsController`, `SwapController`, `SendController`, `TransactionsController`, etc. Views subscribe via `useSnapshot(ControllerState)`. +- **Adapters** — blockchain-specific implementations of the `BlockchainAdapter` interface: ethers/wagmi (EVM), solana, bitcoin. +- **Connectors** — wallet connection methods: `WalletConnectConnector` (default) plus custom ones (Coinbase, Phantom). +- **Namespaces / CAIP** — CAIP-style chain identifiers (`eip155:1`) and addresses (`eip155:1:0x...`). +- **Routing** — `RouterController` navigates between views in `packages/appkit/src/views/`; the up-to-date list of route ids lives in `RouterControllerState` (`packages/core/src/controllers/RouterController.ts`). -**Using Theme**: +Key files: -```typescript -const Theme = useTheme(); -// Returns themed color object that responds to light/dark mode ``` - -### Animation Patterns - -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. - -**Modal Animation** (native driver): - -- Opening: Spring physics (damping: 25, stiffness: 220) -- Closing: Timing animation (150ms) for snappy UX -- Backdrop: Opacity fade (300ms in, 250ms out) - -**Component Animations** (JS-driven, `useNativeDriver: false`): - -- `useAnimatedValue` hook for color interpolation on press states -- `Animated.createAnimatedComponent(Pressable)` for interactive elements -- Color transitions between normal/pressed states - -### Views and Router - -**RouterController** manages navigation between views defined in `RouterControllerState` (see `packages/core/src/controllers/RouterController.ts` for the up-to-date list of route IDs). - -View categories: - -- Account flows (account overview and default account views) -- Connection flows (social logins, external wallets, WalletConnect, etc.) -- Network management (network selection, switching, unsupported network messaging) -- On-ramp experiences (on-ramp setup, checkout, loading, settings) -- Swap flows (swap entry and swap preview/review) -- Wallet actions (receiving, sending, send preview/review) -- Informational views (e.g., "What is a network?", "What is a wallet?") - -**View Pattern**: - -```typescript -export function MyView() { - const snapshot = useSnapshot(ControllerState); - const { padding } = useCustomDimensions(); - - return ( - - {/* Content */} - - ); -} -``` - -### Common UI Patterns - -**FlexView Layout**: - -```typescript - -``` - -**List Item**: - -```typescript - - - {name} - - -``` - -**Button**: - -```typescript - -``` - -### UI Guidelines for Agents - -1. **Use existing components** - Never create custom primitives; use the `wui-*` components -2. **Follow theme system** - All colors must come from theme, no hardcoded hex values -3. **Use FlexView** - Prefer FlexView over View for layout consistency -4. **Spacing tokens** - Use spacing tokens ('xs', 's', 'm', etc.) not pixel values -5. **Animation consistency** - Use `useAnimatedValue` hook for press state animations -6. **Memoize list items** - Use `React.memo` with custom comparison for expensive list items -7. **Test both themes** - Verify changes work in both light and dark mode - ---- - -## Agent Guidance - -### Code Quality Requirements - -**Before pushing any solution, always run:** - -```bash -yarn format # Prettier formatting -yarn lint # ESLint checks -yarn test # Jest tests +packages/appkit/src/AppKit.ts # Main SDK class +packages/appkit/src/hooks/ # useAppKit, useAccount, etc. +packages/core/src/controllers/ # State management controllers +packages/common/src/ # Shared types and network definitions +packages/ethers/src/adapter.ts # EVM adapter implementation ``` -Follow existing code style in the codebase. Do not deviate from established patterns. - -### Platform Compatibility +## UI System -This SDK must work for both **Expo** and **React Native CLI** projects. Ensure any changes are compatible with both environments. +The UI layer is split between two packages: -### Dependency Policy +- `packages/ui/src/` — the reusable library: `components/` (base primitives, `wui-*` names), `composites/` (feature-rich components like Button, ListItem, InputText), `layout/` (`FlexView`, `Overlay`, `Separator`), `hooks/` (`useTheme`, `useAnimatedValue`, `useCustomDimensions`), `utils/` (ThemeUtil holds all color/spacing/typography tokens), `assets/` (SVG icons). +- `packages/appkit/src/` — AppKit-specific UI: `modal/`, `views/` (route views), `partials/` (`w3m-*` composites like header, snackbar, QR code). -**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. +### UI Guidelines -### Key Abstractions +1. **Use existing components** — never create custom primitives; use the `wui-*` components. +2. **Follow the theme system** — all colors come from `useTheme()`; no hardcoded hex values. Works in both light and dark mode — test both. +3. **Use FlexView** — prefer it over `View`; it supports `gap` and padding arrays (`padding={['l', 'xl', 's', 'xl']}` = [top, right, bottom, left]). +4. **Use design tokens** — spacing ('xs', 's', 'm', …), border radius, and typography variants ('paragraph-500', 'small-400', …) are defined in `packages/ui/src/utils/ThemeUtil.ts`; don't use raw pixel values. +5. **Animations** — React Native `Animated` API; native driver for opacity/transforms, `useNativeDriver: false` only for unsupported properties like colors. Use the `useAnimatedValue` hook for press-state color transitions. +6. **Memoize list items** — `React.memo` with a custom comparison for expensive list items. -- **Adapters**: Blockchain-specific implementations (one per chain type) -- **Connectors**: Wallet connection methods -- **Controllers**: Valtio-based reactive state containers -- **Namespaces**: CAIP-style chain identifiers (e.g., `eip155:1` for Ethereum mainnet) -- **CAIP Addresses**: Chain-agnostic addresses (e.g., `eip155:1:0x...`) +When building a view, copy the pattern of an existing one in `packages/appkit/src/views/` (useSnapshot + useCustomDimensions + FlexView). -### Important Files - -``` -packages/appkit/src/AppKit.ts # Main SDK class (~900 LOC) -packages/appkit/src/hooks/ # React hooks (useAppKit, useAccount, etc.) -packages/core/src/controllers/ # State management controllers -packages/common/src/ # Shared types and network definitions -packages/ethers/src/adapter.ts # EVM adapter implementation -packages/solana/src/ # Solana adapter -packages/bitcoin/src/ # Bitcoin adapter -``` - -### Development Commands +## Development ```bash yarn install # Install dependencies yarn ios # Run example on iOS simulator yarn android # Run example on Android emulator yarn build # Build all packages -yarn lint # Run ESLint -yarn test # Run Jest tests -yarn format # Run Prettier ``` -### Commit Convention - -Follow conventional commits: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:` - -### Dependabot Alerts +Running the example app requires a Reown ProjectID: copy `apps/native/.env.example` to `apps/native/.env` and set `EXPO_PUBLIC_PROJECT_ID` (create one at https://dashboard.reown.com). Unit tests and builds need no environment setup. -When resolving Dependabot security alerts or dependency update PRs: - -1. **Direct dependencies** - Update the version directly in the package's `package.json` where it's declared. This is cleaner than using resolutions because: - - - It keeps the dependency version visible where the package is used - - Resolutions are meant for transitive dependencies you don't control - - Example: update storybook in `apps/gallery/package.json`, not via root resolutions +**Before pushing any solution, always run:** -2. **Transitive dependencies** - Use resolutions/overrides for dependencies you don't directly declare: +```bash +yarn format # Prettier +yarn lint # ESLint +yarn test # Jest +``` - - Root `package.json` → `resolutions` field (for yarn workspaces) - - Specific package's `package.json` → `overrides` field (for npm packages like expo-multichain) +### Testing changes -3. **Update lockfiles** - After making changes: +- Unit tests live in each package's `src/__tests__/`. Run one package's tests with `yarn workspace @reown/appkit--react-native test` (faster than the root `yarn test`). +- Jest mocks are shared via `jest-shared-setup.ts`, imported as `@shared-jest-setup` in each package's `jest-setup.ts` — read `TESTING.md` before adding mocks; put shared mocks there, package-specific ones in the package's `jest-setup.ts`. +- New logic in controllers/utils/adapters should come with unit tests following the existing patterns in the package's `__tests__/` folder. +- E2E (Playwright) tests live in `apps/native/tests/`; run them with `yarn playwright:test` from the root (CI runs them via `.github/workflows/e2e.yml`). See `TESTING.md` for details. +- Manual verification: run the example app (`yarn ios` / `yarn android`) for SDK behavior, and `apps/gallery` (Storybook) for isolated UI component changes. - - Run `yarn install` at root to update `yarn.lock` - - Run `npm install` in the specific package directory to update `package-lock.json` +Rules: -4. **Check for related packages** - When updating a package, check if there are related packages that should be updated together (e.g., updating `storybook` should also update all `@storybook/*` addons to the same version for consistency) +- Follow existing code style; do not deviate from established patterns. +- The SDK must work in both **Expo** and **React Native CLI** projects. +- **Keep third-party dependencies minimal** — avoid new libraries; justify any that are absolutely necessary. +- Conventional commits: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`. +- Changesets: a changeset must list **all published packages** (they are versioned together), not only the one you changed. Exception: `@reown/appkit-react-native-cli` is versioned separately — include it only when the CLI itself changes. -5. **Never update to new major versions** - Only apply patch/minor updates. Major version bumps can cause breaking changes and compatibility issues. +## Dependency Updates / Dependabot -6. **Run formatting before committing** - Always run `yarn format` to fix any prettier issues before creating a commit. +1. **Direct dependencies** — update the version in the `package.json` that declares it (e.g. storybook in `apps/gallery/package.json`), not via root resolutions. +2. **Transitive dependencies** — use root `resolutions` (yarn workspaces) or the package's `overrides` field (npm packages like `examples/expo-multichain`). +3. **Lockfiles** — run `yarn install` at root for `yarn.lock`; run `npm install` inside `examples/expo-multichain` for its `package-lock.json`. Verify that example still bundles with `npx expo export`. +4. **Related packages** — update families together (e.g. `storybook` + all `@storybook/*` addons to the same version). +5. **Never bump major versions** — patch/minor only. +6. Run `yarn format` before committing. diff --git a/TESTING.md b/TESTING.md index 20e04d516..22a72b340 100644 --- a/TESTING.md +++ b/TESTING.md @@ -91,83 +91,31 @@ To run tests for a specific package: yarn workspace @reown/appkit-[package-name]-react-native test ``` -## Playwright Testing +## Playwright Testing (E2E) -For end-to-end testing of web interfaces (such as the web demo or web views within the React Native app), we use Playwright. +End-to-end tests run against the example app's web build (Expo web) using Playwright. They run in CI via `.github/workflows/e2e.yml`. -### Setup - -1. Install Playwright: - -```bash -# Install Playwright and browsers -npx playwright install -``` - -2. Playwright tests are located in the `e2e` directory at the root of the project. - -### Writing Tests - -Playwright tests are written using the Playwright Test framework. Here's a basic example: - -```typescript -import { test, expect } from '@playwright/test'; - -test('basic test', async ({ page }) => { - // Navigate to the page - await page.goto('https://your-app-url.com'); - - // Interact with the page - await page.click('text=Sign In'); - await page.fill('input[name="email"]', 'user@example.com'); - await page.fill('input[name="password"]', 'password'); - await page.click('button[type="submit"]'); - - // Assert the result - await expect(page.locator('.welcome-message')).toContainText('Welcome'); -}); -``` - -### Running Playwright Tests - -To run all Playwright tests: - -```bash -yarn playwright:test -``` - -To run a specific test file: - -```bash -yarn playwright:test tests/basic-tests.spec.ts -``` +### Structure -### Debugging Playwright Tests +- Tests: `apps/native/tests/*.spec.ts` (shared helpers in `apps/native/tests/shared/`) +- Config: `apps/native/playwright.config.ts` -To debug tests: +### Running -1. Run with the `--debug` flag: +From the repo root: ```bash -yarn playwright:test --debug +yarn playwright:test # runs all e2e specs (via apps/native) ``` -2. Use the Playwright Inspector to step through the test. - -3. Add `await page.pause()` in your test to pause at a specific point. - -### Generating Test Reports - -To generate an HTML report: +Or from `apps/native`: ```bash -yarn playwright:test --reporter=html +yarn playwright:install # install the chromium browser (first time) +yarn playwright test tests/wallet.spec.ts # run a single spec +yarn playwright test --debug # step through with the Playwright Inspector ``` -Then open the report: - -```bash -yarn playwright:test show-report -``` +An HTML report is written to `apps/native/playwright-report/`; open it with `yarn playwright show-report`. For more information, refer to the [Playwright documentation](https://playwright.dev/docs/intro). diff --git a/package.json b/package.json index fb7af493c..6533d999e 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,7 @@ "packages/bitcoin", "packages/wagmi", "packages/coinbase", + "packages/cli", "apps/*" ], "scripts": { diff --git a/yarn.lock b/yarn.lock index 7b9deac93..5bd562083 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4474,6 +4474,16 @@ __metadata: languageName: node linkType: hard +"@reown/appkit-react-native-cli@workspace:packages/cli": + version: 0.0.0-use.local + resolution: "@reown/appkit-react-native-cli@workspace:packages/cli" + dependencies: + chalk: 5.4.1 + bin: + appkit-react-native: lib/commonjs/index.js + languageName: unknown + linkType: soft + "@reown/appkit-react-native@2.0.4, @reown/appkit-react-native@workspace:*, @reown/appkit-react-native@workspace:packages/appkit": version: 0.0.0-use.local resolution: "@reown/appkit-react-native@workspace:packages/appkit" @@ -8330,6 +8340,13 @@ __metadata: languageName: node linkType: hard +"chalk@npm:5.4.1, chalk@npm:^5.4.1": + version: 5.4.1 + resolution: "chalk@npm:5.4.1" + checksum: 0c656f30b782fed4d99198825c0860158901f449a6b12b818b0aabad27ec970389e7e8767d0e00762175b23620c812e70c4fd92c0210e55fc2d993638b74e86e + languageName: node + linkType: hard + "chalk@npm:^2.0.1, chalk@npm:^2.4.2": version: 2.4.2 resolution: "chalk@npm:2.4.2" @@ -8368,13 +8385,6 @@ __metadata: languageName: node linkType: hard -"chalk@npm:^5.4.1": - version: 5.4.1 - resolution: "chalk@npm:5.4.1" - checksum: 0c656f30b782fed4d99198825c0860158901f449a6b12b818b0aabad27ec970389e7e8767d0e00762175b23620c812e70c4fd92c0210e55fc2d993638b74e86e - languageName: node - linkType: hard - "char-regex@npm:^1.0.2": version: 1.0.2 resolution: "char-regex@npm:1.0.2"