React Native Clean Pattern

Security

Manages end-to-end React Native Expo app lifecycle with strict Controller-View separation, type safety, RTL support, and optimized performance in coder79 eco...

Install

openclaw skills install 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

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:

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

Enum	Key Values
`AuthScreen`	`LOGIN`, `REGISTER`, `FORGOT_PASSWORD`, `OTP_VERIFY`
`ValidationRule`	`REQUIRED`, `EMAIL`, `MIN_LENGTH`, `MATCH`
`UserType`	`USER`, `VENDOR`, `ADMIN`, `DELIVERY_BOY`
`TokenKey`	`ACCESS_TOKEN`, `REFRESH_TOKEN`, `FCM_TOKEN`

§1.2 — Core Application Hooks (`@hooks`)

Hook	Responsibility
`useAppDispatch` / `useAppSelector`	Strictly typed Redux access.
`useRTL`	Manages `I18nManager` force-flipping and app reloads.
`useAppStyle`	Dynamic UI pipe that merges base themes with remote config, resolves RTL directionality (rowDirection, textAlign), and provides centralized design tokens and localized font resolution.
`useAppConfig`	Reactive access to merged Local/Remote Config.
`useColorScheme`	Reactive system theme detection (Light/Dark mode).
`useNotifications`	Orchestrates FCM registration, Notifee channel management, and real-time state rehydration (Profile/Theme) upon receipt of push payloads.

📦 §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)

Component	Purpose	Key Props
`AppText`	Typography with RTL font scaling.	`variant`, `weight`, `align`
`Button`	Themed touchable with loading states.	`title`, `loading`, `icon`, `variant`
`AppHeader`	RTL-aware screen header with back/actions.	`title`, `showBackButton`, `rightComp`
`AppInput`	Validated text input with icons.	`label`, `error`, `icon`, `secure`
`PriceTag`	Currency-aware formatted price display.	`price`, `originalPrice`, `discount`
`AppLoader`	Lottie-powered full-screen or inline loading.	`visible`, `variant`, `message`
`AppModal`	Standardized bottom-sheet or center popup.	`visible`, `onClose`, `title`

🛠️ §4 — Standard Feature Modules

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

Auth Flow: Sign In, Sign Up, OTP, Password Recovery.
Catalog: Product List (FlashList optimized), Category Browse.
Cart & Checkout: Multi-step checkout, Order Summary, Payments.
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:

index.tsx (Skin): Pure JSX. Connects to controller.ts.
controller.ts (Brain): logic hook, utilizes @hooks/useRedux.
styles.ts (Nerves): Function-based styles consuming useAppStyle.
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

npx tsc --noEmit passes with zero errors.
i18n RTL/LTR layout flip verified.
No hardcoded colors/spacing outside of @styles/common.
No relative paths found in imports.
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

Initialize: Generate the package.json, tsconfig.json, and app.json.
Install: Run npm install or bun install to pull the Approved Dependency Matrix.
Environment: Create the .env file from the .env.example template.
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:

Command	Purpose	When to Use
`/provision-app`	Initialize Project	Starting a new app from scratch.
`/setup-api`	API & Observability	Adding a production-grade `apiClient.ts` and `logger.ts`.
`/setup-navigation`	Router Setup	Scaffolding Root (Auth) and Main (Dynamic Tab) navigators.
`/make-screen`	Feature Scaffolding	Creating a new screen using the 4-file MVC-Lite pattern.
`/make-component`	UI Scaffolding	Creating a new Shared, Regular, or Local component.

🔗 Author & Links

GitHub: yahongie2014
Website: coder79.me