react-native-clean-pattern（React native clean pattern 控制）

📱 Clawhub React Native (Expo) Master Skill

A unified, intelligent guide for building and maintaining high-performance mobile applications within the Clawhub ecosystem.

📥 Installation

1. Register the Skill:

Add this directory to your agent's skill path.

2. Environment Setup:

Ensure you have the following global dependencies installed:

npm install -g expo-cli eas-cli react-native-clean-pattern

OR

bun clawdhub install react-native-clean-pattern

⌨️ Usage

To start a new project:

/provision-app

To scaffold a new feature/screen:

/make-screen

To scaffold a new component:

/make-component

To setup API or Navigation infrastructure:

/setup-api
/setup-navigation

🚀 §0 — Execution & Workflow Standards

Follow these steps for any task in the Clawhub ecosystem:

1. STRATEGIZE: Identify if the task is Provisioning (New App), Expansion (New Screen/Feature), or Diagnosis (Bug Fix).
2. AUDIT & CLEAN: Before adding new code, check for Duplicated Files or redundant logic. Reuse existing @shared components or @hooks.
3. SCAFFOLD: If expanding, always create the 4-file MVC-Lite structure.
4. STYLING: Initialize getStyles using the useAppStyle() hook for RTL-compliance. Use HSL tokens from @styles/common.
5. INTEGRATE: Connect UI logic to controller.ts, utilizing @hooks/useRedux and @services/apiClient.
6. SECURE & OPTIMIZE: Ensure mountedRef is used in all async controllers to prevent Memory Leaks.
7. VERIFY: Run npx tsc --noEmit and check RTL/LTR UI toggle.

🏗️ §1 — Project Architecture & Path Aliases

Standardized, strictly typed, and RTL-ready folder architecture. All files must be interconnected via aliases.

.
├── app/                         # Expo Router (routes & layouts)
├── screens/                     # Feature-specific implementations (MVC-Lite)
├── components/                  # Distributed Atom/Molecule components
│   ├── [RegularComponent]/      # Regular/Feature components (e.g., DynamicIsland)
│   └── SharedComponent/         # Global blessed component library (@shared)
├── services/                    # Infrastructure (API, Auth, Firebase, Storage)
├── store/                       # State Management (Redux Power Slices)
├── hooks/                       # Custom logical hooks (@hooks)
├── helpers/                     # Shared pure logic & utilities (@helpers)
├── enums/                       # Global Constants & Types (@enums)
├── styles/                      # Design Token System (@styles)
├── i18n/                        # Localization assets (@i18n)
└── assets/                      # Media & Fonts (@assets)

⭐ Path Alias Enforcement

Never use relative paths (../../). Always use: @shared, @services, @hooks, @store, @helpers, @config, @styles, @enums.

§1.1 — Standardized Enums (@enums)

Use these enums to ensure zero string-literal errors across the app.

§1.2 — Core Application Hooks (@hooks)

📦 §2 — Core Modules (The Gold Standards)

2.1 Configuration System (@config)

Environment-driven, strictly typed central config:

• Environment: Mapped to .env variables via process.env.
• Typing: Governed by the AppConfig interface.
• Safety: Includes fallbacks and platform-specific logic.

2.2 API Client (@services/apiClient)

Singleton wrapper with:

• Auth: Automatic Bearer token injection.
• I18n: Reactive Accept-Language headers.
• Payloads: Native support for JSON and FormData.
• Logging: Detailed request/response tracing with duration.

2.3 Auth Service (@services/authService)

Orchestrator for Login, Register, OTP, and Profile management with:

• Multi-Method Support: Native handling for EMAIL_PASSWORD, EMAIL_OTP, and PHONE_OTP.
• UserType Injection: Context-aware management of delivery, vendor, or customer states.
• Redux Integration: Synchronized state for OTP sending status and active auth methods.

2.4 Firebase Service (@services/firebaseService)

Platform-aware initialization for Expo Go and Development Builds.

2.5 Notification Service (@services/notificationService)

Management of paginated alert listing and "read" state synchronization.

2.6 Security Storage (@services/tokenStorage)

Encrypted or AsyncStorage persistence for tokens and user metadata.

2.7 Consolidated Logging (@helpers/logger)

Sensitized logging system with:

• Redaction: Automatic sanitization of sensitive fields (password, token, authorization, otp).
• Tracing: Structured request(), response(), and error() tracing with latency tracking.
• Observability: Seamless Sentry integration via addBreadcrumb and captureException.
• Environment Aware: Debug-only rich formatting (__DEV__) with terminal icons (🌐, ✅, ❌, 🔴, ℹ️, ⚠️).

2.8 Localization (@i18n)

RTL-First standard with:

• Engine: i18next with compatibilityJSON: 'v3' for React Native safe pluralization.
• Persistence: Mandatory AsyncStorage usage to remember language selection across reloads.
• Hypdration: initializeI18n() async boot sequence required in _layout.tsx.
• RTL: I18nManager force-flip with expo-updates reload (try/catch protected).
• State Sync: Must use a callback pattern for Redux synchronization; NEVER import store directly into the i18n instance.
• Reload: Integration with expo-updates for mandatory UI rehydration on direction change.
• Sync: setupRTL() boot helper to maintain state consistency.

2.9 Redux Toolkit Power Slices (@store)

Strictly typed state management with:

• Hooks: Mandatory use of useAppDispatch and useAppSelector for type-safe state access.
• Pillars: Auth (Session/User/AuthMethod), App (Theme/Language/RTL), and Notification (Alerts) slices.

🧩 §3 — Standard Component Library (@shared)

🛠️ §4 — Standard Feature Modules

Implemented as isolated folders under screens/ following MVC-Lite:

1. Auth Flow: Sign In, Sign Up, OTP, Password Recovery.
2. Catalog: Product List (FlashList optimized), Category Browse.
3. Cart & Checkout: Multi-step checkout, Order Summary, Payments.
4. Profile: User Details, Address Management, Order History.

📚 §5 — Approved Dependency Matrix

• Core: expo@~55.0.5, react@19.2.0, react-native@0.83.2.
• Navigation: @react-navigation/native, @react-navigation/native-stack, @react-navigation/bottom-tabs.

* Standards: Dynamic configuration-driven Bottom Tabs and Auth/Guest gating with Navigator-level key remounting.

• State & Logic: @reduxjs/toolkit@^2.11.2, react-redux@^9.2.0.
• Networking & Auth: @react-native-firebase/app, @react-native-firebase/messaging.
• Persistence: @react-native-async-storage/async-storage@^2.2.0.
• Internationalization: i18next@^25.8.16, react-i18next@^16.5.6, expo-localization.
• UI & Visuals: lottie-react-native@~7.3.4, react-native-reanimated@4.2.1, react-native-render-html.
• Maps & Location: react-native-maps, react-native-maps-directions, expo-location.
• Typography: @expo-google-fonts/cairo, @expo-google-fonts/outfit, @expo-google-fonts/roboto.
• Observability: @sentry/react-native@~7.11.0.
• Native Features: @notifee/react-native, expo-image-picker, expo-document-picker.

🧱 §6 — Expansion Pattern (MVC-Lite)

Every new screen, feature, OR shared component MUST consist of exactly 4 files:

1. index.tsx (Skin): Pure JSX. Connects to controller.ts.
2. controller.ts (Brain): logic hook, utilizes @hooks/useRedux.
3. styles.ts (Nerves): Function-based styles consuming useAppStyle.
4. types.ts (Structure): Interface definitions. Zero any.

🛡️ §7 — Defensive Coding & Security

• Memory Safety: Always use isMounted ref in controllers. Abort all API calls in useEffect cleanup.
• Zero Duplication: Shared logic must stay in @hooks or @helpers. Don't copy-paste styles; use @styles/common. Hard Requirement: All sizes, spacing, and colors must be consumed via useAppStyle().tokens and useAppStyle().colors.
• Zero Hardcoding: Using literal hex codes (#FFFFFF) or RGBA strings in UI components is FORBIDDEN. All UI colors must be resolved from the colors object provided by the central styling hook.
• Zero Inline Styles: Using the style={{ ... }} prop in JSX is FORBIDDEN for layout and presentation. All styles MUST be defined in the accompanying styles.ts file and resolve via the screen/component controller to ensure theme and RTL reactivity.
• Branding Sync: Primary theme colors MUST be defined in src/config/index.ts and consumed via @constants/Colors.ts to support white-labeling and remote branding.
• RTL Enforcement: Use rowDirection and textAlign from useAppStyle.
• Sanitization: Never log raw bodies containing password or token.
• Absolute Paths: All imports MUST use standardized aliases. Relative paths (../../) are forbidden.

* Standard Aliases: @/, @components, @hooks, @constants, @store, @i18n, @assets, @config, @app-types, @enums, @utils, @helpers, @services, @screens, @styles.

✅ §8 — Verification Checklist

1. [ ] npx tsc --noEmit passes with zero errors.
2. [ ] i18n RTL/LTR layout flip verified.
3. [ ] No hardcoded colors/spacing outside of @styles/common.
4. [ ] No relative paths found in imports.
5. [ ] Async logic verified for mountedRef safety.

🏗️ §9 — Provisioning Guide (Training)

When starting a NEW application, you must follow this interactive training flow to ensure architectural integrity without merely copy-pasting old classes.

1. The Inquiry Phase

You MUST ask the user for authorization to implement:

• Project Identity: Targeted app name and bundle identifier.
• Localization: RTL support needs and target languages (LTR: EN, ES, FR, etc. | RTL: AR, HE, FA, etc.).
• Core Screens:

- app/_layout.tsx: Master orchestrator (Sentry, Redux, RTL, Hydration). - app/(auth): Auth flow group (Login, Register, OTP). - app/(tabs): Main application navigation.

• Core Auth: Login, Register, OTP, and Forgot Password recovery screens.
• State Architecture: Redux Toolkit (Auth/App/Notify slices).
• Native Bridges: Firebase Messaging and Notifee.
• Observation Layer: Sentry integration and Custom Logger.
• Persistence: Encrypted Token Storage.

2. The Structural Blueprint

Instead of copying files, generate fresh implementations based on these patterns:

• Auth (MVC-Lite): Each screen (Login, Register, OTP) gets its own Skin, Brain, Nerves, and Structure.
• Services: Freshly authored apiClient.ts and authService.ts.
• Global Store: A clean Redux initialization with strictly typed slices.

3. The Activation Loop

1. Initialize: Generate the package.json, tsconfig.json, and app.json.
2. Install: Run npm install or bun install to pull the Approved Dependency Matrix.
3. Environment: Create the .env file from the .env.example template.
4. Launch: Execute npx expo start to verify the baseline.

⌨️ §10 — Workflow & Slash Command Reference

Use these commands to automate common development tasks within the Clawhub ecosystem:

🔗 Author & Links

• GitHub: yahongie2014
• Website: coder79.me