theone-react-native-standards

name	theone-react-native-standards
description	Enforces TheOne Studio React Native development standards including TypeScript patterns, React/Hooks best practices, React Native architecture (Zustand/Jotai, Expo Router), and mobile performance optimization. Triggers when writing, reviewing, or refactoring React Native code, implementing mobile features, working with state management/navigation, or reviewing pull requests.

TheOne Studio React Native Development Standards

⚠️ React Native Latest + TypeScript: All patterns use latest React Native with TypeScript strict mode, Expo SDK 51+, and modern React 18+ patterns.

Skill Purpose

This skill enforces TheOne Studio's comprehensive React Native development standards with CODE QUALITY FIRST:

Priority 1: Code Quality & Hygiene (MOST IMPORTANT)

• TypeScript strict mode, ESLint + Prettier enforcement
• Path aliases (@/), throw errors (never suppress), structured logging
• No any types, proper error boundaries, consistent imports
• File naming conventions, no inline styles in JSX

Priority 2: Modern React & TypeScript

• Functional components with Hooks (NO class components)
• Custom hooks for logic reuse, proper memoization
• Type-safe props, generics, discriminated unions
• useCallback/useMemo for performance

Priority 3: React Native Architecture

• Zustand/Jotai for state (document both, require consistency per project)
• Expo Router (file-based) OR React Navigation 7
• FlatList optimization (NEVER ScrollView + map)
• Platform-specific code (.ios.tsx/.android.tsx)

Priority 4: Mobile Performance

• List rendering optimization (getItemLayout, keyExtractor)
• Prevent unnecessary rerenders (React.memo, shouldComponentUpdate)
• Lazy loading, code splitting, bundle optimization
• Memory leak prevention (cleanup effects)

When This Skill Triggers

• Writing or refactoring React Native TypeScript code
• Implementing mobile UI components or features
• Working with state management (Zustand/Jotai)
• Implementing navigation flows (Expo Router/React Navigation)
• Optimizing list rendering or app performance
• Reviewing React Native pull requests
• Setting up project architecture or conventions

Quick Reference Guide

What Do You Need Help With?

Priority	Task	Reference
🔴 PRIORITY 1: Code Quality (Check FIRST)
1	TypeScript strict, ESLint, Prettier, no any types	Quality & Hygiene ⭐
1	Path aliases (@/), structured logging, error handling	Quality & Hygiene ⭐
1	File naming, no inline styles, consistent imports	Quality & Hygiene ⭐
🟡 PRIORITY 2: Modern React/TypeScript
2	Functional components, Hooks rules, custom hooks	Modern React
2	useCallback, useMemo, React.memo optimization	Modern React
2	Type-safe props, generics, utility types	TypeScript Patterns
2	Discriminated unions, type guards, inference	TypeScript Patterns
🟢 PRIORITY 3: React Native Architecture
3	Functional components, composition, HOCs	Component Patterns
3	Zustand patterns, Jotai atoms, persistence	State Management
3	Expo Router (file-based), React Navigation setup	Navigation
3	Platform checks, .ios/.android files, Platform module	Platform-Specific
🔵 PRIORITY 4: Performance
4	FlatList optimization, getItemLayout, keyExtractor	Performance
4	Rerender prevention, React.memo, useMemo	Performance
4	Architecture violations (components, state, navigation)	Architecture Review
4	TypeScript quality, hooks violations, ESLint	Quality Review
4	List optimization, memory leaks, unnecessary rerenders	Performance Review

🔴 CRITICAL: Code Quality Rules (CHECK FIRST!)

⚠️ MANDATORY QUALITY STANDARDS

ALWAYS enforce these BEFORE writing any code:

1. TypeScript strict mode - Enable all strict compiler options
2. ESLint + Prettier - Enforce linting and formatting
3. No any types - Use proper types or unknown
4. Path aliases - Use @/ for src/ imports
5. Throw errors - NEVER suppress errors with try/catch + console.log
6. Structured logging - Use logger utility, not raw console.log
7. Error boundaries - Wrap components with ErrorBoundary
8. Consistent imports - React first, then libraries, then local
9. File naming - kebab-case for files, PascalCase for components
10. No inline styles in JSX - Define styles outside component or use StyleSheet

Example: Enforce Quality First

// ✅ EXCELLENT: All quality rules enforced

// 1. TypeScript strict mode in tsconfig.json
// {
//   "compilerOptions": {
//     "strict": true,
//     "noImplicitAny": true,
//     "strictNullChecks": true
//   }
// }

// 2. Import order: React → libraries → local
import React, { useCallback, useMemo } from 'react'; // React first
import { View, Text, StyleSheet } from 'react-native'; // Libraries
import { useStore } from '@/stores/user-store'; // Local with path alias

// 3. Type-safe props (no any)
interface UserProfileProps {
  userId: string;
  onPress?: () => void;
}

// 4. Functional component with typed props
export const UserProfile: React.FC<UserProfileProps> = ({ userId, onPress }) => {
  const user = useStore((state) => state.users[userId]);

  // 5. Throw errors (not console.log)
  if (!user) {
    throw new Error(`User not found: ${userId}`);
  }

  // 6. Structured logging
  const handlePress = useCallback(() => {
    logger.info('User profile pressed', { userId });
    onPress?.();
  }, [userId, onPress]);

  return (
    <View style={styles.container}>
      <Text style={styles.name}>{user.name}</Text>
    </View>
  );
};

// 7. No inline styles - use StyleSheet
const styles = StyleSheet.create({
  container: {
    padding: 16,
  },
  name: {
    fontSize: 18,
    fontWeight: 'bold',
  },
});

⚠️ React Native Architecture Rules (AFTER Quality)

Choose Consistent State Management

Choose ONE state management solution per project:

Option 1: Zustand (Recommended for Simple State)

• ✅ Minimal boilerplate, hooks-based
• ✅ Perfect for app-level state (user, settings)
• ✅ Easy to test, TypeScript-friendly

Option 2: Jotai (Recommended for Atomic State)

• ✅ Atomic state management
• ✅ Perfect for complex derived state
• ✅ Better for fine-grained reactivity

Universal Rules (Both Solutions):

• ✅ Use selectors to prevent unnecessary rerenders
• ✅ Keep state normalized (no nested objects)
• ✅ Persist state with async storage adapters
• ✅ NEVER use Redux (too much boilerplate)

Choose ONE Navigation Solution

Option 1: Expo Router (Recommended)

• ✅ File-based routing (app/ directory)
• ✅ Built-in TypeScript support
• ✅ Automatic deep linking

Option 2: React Navigation 7

• ✅ More control over navigation structure
• ✅ Better for complex navigation flows
• ✅ Proven stability

ALWAYS Use FlatList for Lists

NEVER use ScrollView + map for lists:

// ❌ BAD: ScrollView + map (terrible performance)
<ScrollView>
  {items.map(item => <Item key={item.id} {...item} />)}
</ScrollView>

// ✅ GOOD: FlatList with proper optimization
<FlatList
  data={items}
  renderItem={({ item }) => <Item {...item} />}
  keyExtractor={(item) => item.id}
  getItemLayout={(data, index) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * index,
    index,
  })}
  removeClippedSubviews
  maxToRenderPerBatch={10}
  windowSize={11}
/>

Quick Examples: ❌ BAD vs ✅ GOOD

Example 1: Component Structure

// ❌ BAD: Class component, inline styles, no types
class UserCard extends React.Component {
  render() {
    return (
      <View style={{ padding: 10 }}>
        <Text>{this.props.name}</Text>
      </View>
    );
  }
}

// ✅ GOOD: Functional component, typed props, StyleSheet
interface UserCardProps {
  name: string;
  onPress?: () => void;
}

export const UserCard: React.FC<UserCardProps> = ({ name, onPress }) => {
  return (
    <View style={styles.container}>
      <Text style={styles.name}>{name}</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: { padding: 10 },
  name: { fontSize: 16 },
});

Example 2: State Management

// ❌ BAD: useState for app-level state
function App() {
  const [user, setUser] = useState(null);
  const [settings, setSettings] = useState({});

  return <AppContent user={user} settings={settings} />;
}

// ✅ GOOD: Zustand for app-level state
import { create } from 'zustand';

interface AppState {
  user: User | null;
  settings: Settings;
  setUser: (user: User | null) => void;
}

export const useAppStore = create<AppState>((set) => ({
  user: null,
  settings: {},
  setUser: (user) => set({ user }),
}));

function App() {
  const user = useAppStore((state) => state.user);
  return <AppContent />;
}

Example 3: List Rendering

// ❌ BAD: ScrollView + map
<ScrollView>
  {users.map(user => (
    <UserCard key={user.id} user={user} />
  ))}
</ScrollView>

// ✅ GOOD: FlatList with optimization
const ITEM_HEIGHT = 80;

<FlatList
  data={users}
  renderItem={({ item }) => <UserCard user={item} />}
  keyExtractor={(item) => item.id}
  getItemLayout={(_, index) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * index,
    index,
  })}
/>

Common Mistakes to Avoid

🔴 Critical Mistakes

Mistake	Why It's Wrong	Correct Approach
Using class components	Outdated, verbose, no hooks	Use functional components
Using any type	Defeats TypeScript safety	Use proper types or unknown
Inline styles in JSX	Poor performance, not reusable	Use StyleSheet.create()
ScrollView + map for long lists	Memory issues, poor performance	Use FlatList with optimization
Direct console.log	Not structured, no filtering	Use logger utility

🟡 Warning-Level Mistakes

Mistake	Why It's Wrong	Correct Approach
Not using path aliases	Ugly relative imports	Configure @/ alias
Missing keyExtractor	Poor list performance	Always provide keyExtractor
Not memoizing callbacks	Causes unnecessary rerenders	Use useCallback
Platform checks in render	Duplicated logic	Use Platform-specific files
Not cleaning up effects	Memory leaks	Return cleanup function

🟢 Optimization Opportunities

Pattern	Issue	Optimization
Expensive calculations in render	Recalculates every render	Use useMemo
Props causing child rerenders	Child rerenders unnecessarily	Use React.memo
Large lists without optimization	Slow scrolling	Add getItemLayout
Deep object comparisons	Expensive checks	Use shallow equality
Large bundles	Slow app startup	Code splitting, lazy loading

Code Review Checklist

Use this checklist when reviewing React Native code:

🔴 Critical Issues (Block Merge)

• TypeScript strict mode enabled
• No any types used
• ESLint + Prettier passing
• Path aliases (@/) configured and used
• Errors are thrown (not suppressed)
• Error boundaries wrap components
• FlatList used for lists (not ScrollView + map)
• File naming follows conventions (kebab-case)

🟡 Important Issues (Request Changes)

• Functional components used (no class components)
• Props are properly typed
• Hooks rules followed (no conditionals, no loops)
• useCallback/useMemo used appropriately
• Styles use StyleSheet (no inline styles)
• State management is consistent (Zustand OR Jotai)
• Navigation is consistent (Expo Router OR React Navigation)
• Platform-specific code properly handled

🟢 Suggestions (Non-Blocking)

• Custom hooks extract reusable logic
• React.memo used for expensive components
• getItemLayout provided for FlatList
• Effect cleanup functions provided
• Code splitting for large screens
• Images optimized and lazy loaded
• Accessibility props added (accessibilityLabel)

Framework Versions

Recommended Stack:

• React Native: 0.74+ (latest stable)
• Expo SDK: 51+ (if using Expo)
• TypeScript: 5.4+
• React: 18.2+
• Zustand: 4.5+ OR Jotai: 2.8+
• Expo Router: 3.5+ OR React Navigation: 7+

Development Tools:

• ESLint: 8.57+ with @react-native-community plugin
• Prettier: 3.2+
• Metro bundler (built-in)
• React DevTools: Latest

Reference Files Structure

All detailed patterns and examples are in reference files:

Language Patterns (TypeScript + React)

• Quality & Hygiene - TypeScript strict, ESLint, path aliases, error handling
• Modern React - Hooks, functional components, memoization
• TypeScript Patterns - Type-safe props, generics, utility types

Framework Patterns (React Native)

• Component Patterns - Functional components, composition, HOCs
• State Management - Zustand, Jotai, persistence
• Navigation Patterns - Expo Router, React Navigation, deep linking
• Platform-Specific - iOS/Android differences, platform files
• Performance Patterns - FlatList optimization, rerender prevention

Code Review Guidelines

• Architecture Review - Component violations, state issues
• Quality Review - TypeScript quality, hooks violations
• Performance Review - List optimization, memory leaks