⚡ OptiCore React Native

The Ultimate Infrastructure Library for React Native & Expo

OptiCore is a TypeScript-first, production-ready infrastructure layer that eliminates boilerplate and accelerates development. One library. Every layer covered.

🔥 Why OptiCore?

• Zero Boilerplate — ApiClient, Logger, Storage, State — all wired up in minutes

• Type-Safe by Design — Strict TypeScript with zero any tolerance

• Offline-First Ready — Built-in queue, sync engine, and conflict resolution

• Extensible Architecture — Interceptors, auth strategies, pluggable log transports

• 11 Custom Hooks — Async state, debounce, keyboard, network, performance & more

• Form Infrastructure — Zod + React Hook Form with masks, validation, and i18n

• Theme Engine — Dynamic theming with dark mode, spacing, typography & shadows

• 604 Tests Passing — Battle-tested, production-grade quality

📦 Installation

npm install opticore-react-native
# or
yarn add opticore-react-native

Peer Dependencies

Install all peer dependencies with one command:

npx install-peerdeps opticore-react-native

This uses install-peerdeps to automatically resolve and install the correct versions of all required peer dependencies.

🚀 Quick Start

Step 1 — Wrap your app root

import { OptiCoreProvider, LogLevel } from 'opticore-react-native';
import { StorageManager } from 'opticore-react-native';

export default function RootLayout() {
  return (
    <OptiCoreProvider
      config={{
        api: {
          baseURL: 'https://api.example.com',
          getAuthToken: () => StorageManager.getInstance().secure.get<string>('token'),
          onTokenRefresh: async () => {
            const newToken = await refreshToken();
            await StorageManager.getInstance().secure.set('token', newToken);
            return newToken;
          },
        },
        logger: { level: __DEV__ ? LogLevel.DEBUG : LogLevel.WARN },
        theme: { defaultMode: 'system' },
        offline: { syncOnReconnect: true },
        features: { debugMode: __DEV__ },
      }}
    >
      <Stack />
    </OptiCoreProvider>
  );
}

OptiCoreProvider initializes all singletons, sets up React Query, wires theming, and handles cleanup — no extra setup needed.

Step 2 — Start using the library

import { ApiClient, StorageManager, Logger } from 'opticore-react-native';
import { useAsyncState } from 'opticore-react-native/hooks';

// HTTP requests — auth token injected automatically
const { data } = await ApiClient.getInstance().get<User[]>('/users');

// Storage — automatic JSON serialization
await StorageManager.getInstance().local.set('user', { id: 1, name: 'Ali' });

// Logging — level-filtered, transport-ready
Logger.getInstance().info('App ready', { userId: '123' });

// Async state in components
const { data: users, isLoading, error, run } = useAsyncState<User[]>();
run(() => ApiClient.getInstance().get<User[]>('/users').then(r => r.data));

→ Full setup guide — auth, error handling, offline sync, theming and more.

📖 Documentation

Getting Started

| Guide | Description | |---|---| | 🚀 Quick Start | Install, configure, and make your first API call in 10 minutes | | 🏛 Architecture | Library layers, data flow, design patterns, and extension points | | ⚙️ Configuration | Every CoreConfig option explained with examples | | 📑 Full Docs Index | Central navigation hub for all documentation |

API Reference

| Guide | Description | |---|---| | 🏗 Infrastructure | ApiClient, Logger, StorageManager, ConnectivityManager, LifecycleManager | | 🗄 State Management | AsyncState, BaseStore, CrudStore, StoreFactory, StateObserver | | 🪝 Hooks | 11 custom hooks — useAsyncState, useDebounce, useKeyboard, useConnectivity & more | | ⚠️ Error Handling | RenderError, NonRenderError, ApiError, Result<T,E>, ErrorBoundary | | 🛠 Utilities | 40+ pure functions — string, number, array, date, object, format, color, platform | | 🧭 Navigation | useRouteHelper, Expo Router integration | | 🔷 Types | All shared TypeScript types — ApiResponse, AsyncState, PaginatedResponse & more |

Feature Guides

| Guide | Description | |---|---| | 🎨 Theme Engine | Dynamic theming, dark mode, custom themes, ThemeManager | | 📋 Forms | useFormState, Zod validation, input masks, field-level validation | | 📡 Offline Sync | Request queue, auto-sync on reconnect, conflict resolution |

Project Guides

| Guide | Description | |---|---| | 🔄 Migration | Migrate from Redux, MobX, plain Axios, AsyncStorage, console.log | | 🧪 Testing | Mock helpers, test patterns, coverage requirements | | ❓ FAQ | Common questions, troubleshooting, platform notes |

❗ Issues & Contributions

Found a bug or want a feature? Open an issue on GitHub Issues.

Please include:

• Clear description of the issue
• Steps to reproduce
• OptiCore version
• Relevant code snippets

Contributions are welcome — check the Contributing Guide.

📜 Changelog

See CHANGELOG.md for release history and migration notes.

👤 Created By

Built with ❤️ by Mahmoud El Shenawy

📜 License

OptiCore React Native is open-source software released under the MIT License.

Free to use, modify, and distribute — in personal and commercial projects.