React Native Clean Pattern

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

Security Scan

The skill is an instruction-only scaffolding/architecture guide for Expo/React Native and its requirements and instructions are consistent with that purpose.

Purpose & Capability

The name and description match the provided instructions and workflows (project provisioning, scaffolding, API/navigation setup). The skill does not request unrelated binaries, credentials, or config paths.

Instruction Scope

SKILL.md contains scaffolding and coding guidance restricted to project structure, hooks, services, and tooling. It references process.env for app config (expected for an app template) but does not instruct reading or exfiltrating unrelated system files or credentials.

Install Mechanism

This is an instruction-only skill with no install spec or code to be written to disk. It suggests installing common dev dependencies (expo-cli, eas-cli, etc.) which is appropriate for the described tasks.

Credentials

The skill declares no required environment variables or credentials. It advises using process.env for API URLs, Firebase keys, and Sentry DSN as part of normal app configuration; those references are expected for this purpose and are not requested by the skill itself.

Persistence & Privilege

The skill does not request persistent platform privileges (always is false) and does not modify other skills or system-wide settings. Autonomous invocation is allowed (default) but not accompanied by other risky capabilities.

Assessment

This skill is a documentation/scaffolding guide and appears internally consistent. Before using it, verify any npm packages it recommends (expo-cli, eas-cli, react-native-clean-pattern) come from trusted authors/registries and inspect any generated project files or install scripts before running them. Keep secrets (Sentry DSN, Firebase keys, API secrets) in a secure env store and do not paste them into public scaffolding or logs. If you plan to run agent-provided shell commands, review them first to ensure they do what you expect.

📱 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.

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:

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:

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