Skip to content

Commit 4b1944a

Browse files
cmcWebCode40claude
cmcWebCode40
and
claude
committed
docs: add CLAUDE.md development guide and update package.json
Add comprehensive development guide documenting project architecture, component design system, configuration interfaces, and development workflow. Update package.json with any necessary changes. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 61d06f2 commit 4b1944a

2 files changed

Lines changed: 200 additions & 2 deletions

File tree

‎CLAUDE.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# React Native API Debugger - Development Guide
2+
3+
## Project Overview
4+
5+
A comprehensive network request debugging SDK for React Native applications. Intercepts and visualizes HTTP requests with a draggable overlay interface.
6+
7+
## Architecture
8+
9+
### Directory Structure
10+
11+
```
12+
src/
13+
├── index.tsx # Public API exports
14+
├── types.ts # TypeScript interfaces and types
15+
├── NetworkInterceptor.ts # Core request interception engine
16+
├── NetworkLoggerOverlay.tsx # Main overlay container component
17+
├── NetworkLogItem.tsx # Individual log entry component
18+
├── FloatingButton.tsx # Draggable trigger button
19+
├── NonFloatingButton.tsx # Static trigger button fallback
20+
├── CopyItem.tsx # Clipboard copy component
21+
├── Icon.tsx # Emoji-based icon component
22+
├── components/ # Reusable UI components (new)
23+
│ ├── index.ts # Component exports
24+
│ ├── Badge.tsx # Status badge component
25+
│ ├── FilterChip.tsx # Filter tag component
26+
│ ├── SearchInput.tsx # Search input component
27+
│ └── JsonViewer.tsx # JSON tree viewer component
28+
├── hooks/ # Custom React hooks (new)
29+
│ ├── index.ts # Hook exports
30+
│ ├── useNetworkLogs.ts # Log subscription hook
31+
│ └── useFilteredLogs.ts # Log filtering hook
32+
├── utils/ # Utility functions (new)
33+
│ ├── index.ts # Utility exports
34+
│ ├── formatters.ts # Data formatting utilities
35+
│ ├── curl.ts # cURL generation
36+
│ └── filters.ts # Filter logic
37+
└── constants/ # Constants and config (new)
38+
├── index.ts # Constants exports
39+
├── colors.ts # Color palette
40+
└── config.ts # Default configuration
41+
```
42+
43+
### Component Design System
44+
45+
#### Design Principles
46+
47+
1. **Single Responsibility**: Each component handles one concern
48+
2. **Composition over Inheritance**: Build complex UIs from simple pieces
49+
3. **Graceful Degradation**: Features work without optional dependencies
50+
4. **Zero Config Defaults**: Works out of the box with sensible defaults
51+
5. **TypeScript First**: Full type safety with exported interfaces
52+
53+
#### Component Categories
54+
55+
| Category | Purpose | Examples |
56+
|----------|---------|----------|
57+
| **Core** | Business logic & interception | `NetworkInterceptor` |
58+
| **Container** | State management & data flow | `NetworkLoggerOverlay` |
59+
| **Presentational** | Pure UI rendering | `NetworkLogItem`, `Badge`, `FilterChip` |
60+
| **Interactive** | User interaction handling | `FloatingButton`, `CopyItem` |
61+
| **Utility** | Shared functionality | `Icon`, `JsonViewer` |
62+
63+
#### Reusable Component Guidelines
64+
65+
```typescript
66+
// Component Template
67+
interface ComponentProps {
68+
// Required props first
69+
requiredProp: string;
70+
// Optional props with defaults
71+
optionalProp?: boolean;
72+
// Style overrides last
73+
style?: StyleProp<ViewStyle>;
74+
}
75+
76+
const Component: React.FC<ComponentProps> = ({
77+
requiredProp,
78+
optionalProp = false,
79+
style,
80+
}) => {
81+
// Implementation
82+
};
83+
```
84+
85+
### State Management
86+
87+
- **Local State**: React `useState` for component-specific state
88+
- **Shared State**: Pub/sub pattern via `NetworkLogger.subscribe()`
89+
- **No External Dependencies**: No Redux/MobX required
90+
91+
### Styling Conventions
92+
93+
- Use `StyleSheet.create()` for all styles
94+
- Define styles at bottom of component file
95+
- Use semantic color names from `constants/colors.ts`
96+
- Support both light and dark themes
97+
98+
## Configuration
99+
100+
### NetworkLogger Config Interface
101+
102+
```typescript
103+
interface NetworkLoggerConfig {
104+
maxLogs: number; // Default: 100
105+
ignoredUrls: string[]; // URL patterns to ignore
106+
ignoredDomains: string[]; // Domains to ignore
107+
redactHeaders: string[]; // Headers to mask (e.g., 'Authorization')
108+
enablePersistence: boolean; // Persist logs across sessions
109+
slowRequestThreshold: number; // ms threshold for slow request warning
110+
}
111+
```
112+
113+
### Overlay Config Interface
114+
115+
```typescript
116+
interface NetworkLoggerOverlayProps {
117+
networkLogger: NetworkLogger;
118+
// Feature flags
119+
draggable?: boolean;
120+
enableDeviceShake?: boolean;
121+
useCopyToClipboard?: boolean;
122+
// Display options
123+
showRequestHeader?: boolean;
124+
showResponseHeader?: boolean;
125+
theme?: 'light' | 'dark' | 'auto';
126+
// Filtering
127+
defaultFilters?: FilterConfig;
128+
}
129+
```
130+
131+
## Development Workflow
132+
133+
### Commands
134+
135+
```bash
136+
# Install dependencies
137+
yarn install
138+
139+
# Run example app
140+
yarn example start
141+
142+
# Type checking
143+
yarn typecheck
144+
145+
# Linting
146+
yarn lint
147+
148+
# Run tests
149+
yarn test
150+
151+
# Build library
152+
yarn prepare
153+
154+
# Release
155+
yarn release
156+
```
157+
158+
### Adding New Features
159+
160+
1. Create feature branch from `main`
161+
2. Add types to `types.ts`
162+
3. Implement in appropriate directory (components/hooks/utils)
163+
4. Export from index files
164+
5. Add example usage in `example/src/`
165+
6. Update README if public API changes
166+
7. Write tests for new functionality
167+
168+
### Testing Strategy
169+
170+
- Unit tests for utility functions
171+
- Component tests for UI components
172+
- Integration tests for interceptor logic
173+
- Manual testing via example app
174+
175+
## Optional Peer Dependencies
176+
177+
| Package | Required For |
178+
|---------|--------------|
179+
| `react-native-gesture-handler` | Draggable floating button |
180+
| `react-native-reanimated` | Smooth animations |
181+
| `react-native-shake` | Device shake detection |
182+
| `@react-native-clipboard/clipboard` | Copy to clipboard |
183+
184+
## Code Style
185+
186+
- Use TypeScript strict mode
187+
- Prefer functional components with hooks
188+
- Use explicit return types on functions
189+
- Document public APIs with JSDoc
190+
- Follow React Native community conventions
191+
192+
## Performance Guidelines
193+
194+
- Limit stored logs (default: 100)
195+
- Use `FlatList` with optimization props
196+
- Lazy load optional dependencies
197+
- Avoid re-renders with `React.memo` where appropriate
198+
- Use `useCallback` for event handlers passed as props

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,12 +87,12 @@
8787
"typescript": "^5.8.3"
8888
},
8989
"peerDependencies": {
90+
"@react-native-clipboard/clipboard": "*",
9091
"react": "*",
9192
"react-native": "*",
9293
"react-native-gesture-handler": "2.24.0",
9394
"react-native-reanimated": "3.19.1",
94-
"react-native-shake": "*",
95-
"@react-native-clipboard/clipboard": "*"
95+
"react-native-shake": "*"
9696
},
9797
"workspaces": [
9898
"example"

0 commit comments

Comments
 (0)