rn-remote-config

A lightweight, SOLID-compliant remote configuration library for React Native with support for custom offline caching engines (such as AsyncStorage, react-native-mmkv, etc.).

Features

• SOLID Architecture: Fully decoupled storage and fetcher layers.
• Offline-First / Cache-First: Loads local cache immediately for fast app startup, then updates values in the background.
• Custom Caching: Easily swap cache engines (e.g. AsyncStorage, MMKV).
• React Hooks: Simple hooks (useRemoteConfig and useRemoteValue) to access remote config values reactively.

Installation

yarn add rn-remote-config

Note: Make sure you also install your preferred storage engine (like @react-native-async-storage/async-storage or react-native-mmkv) since this library does not bundle any storage engine directly.

Quick Start

1. Implement IStorage Wrapper

You need to provide a custom storage class that conforms to the IStorage interface:

export interface IStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example using react-native-mmkv:

// MMKVStorage.ts
import { MMKV } from "react-native-mmkv";
import { IStorage } from "rn-remote-config";

const mmkv = new MMKV();

export class MMKVStorage implements IStorage {
  async getItem(key: string): Promise<string | null> {
    const value = mmkv.getString(key);
    return value !== undefined ? value : null;
  }

  async setItem(key: string, value: string): Promise<void> {
    mmkv.set(key, value);
  }

  async removeItem(key: string): Promise<void> {
    mmkv.delete(key);
  }
}

Example using @react-native-async-storage/async-storage:

// AsyncStorageStorage.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { IStorage } from "rn-remote-config";

export class AsyncStorageStorage implements IStorage {
  async getItem(key: string): Promise<string | null> {
    return await AsyncStorage.getItem(key);
  }

  async setItem(key: string, value: string): Promise<void> {
    await AsyncStorage.setItem(key, value);
  }

  async removeItem(key: string): Promise<void> {
    await AsyncStorage.removeItem(key);
  }
}

2. Wrap your App with RemoteConfigProvider

Initialize the provider at the root of your application and pass your custom storage instance:

import React from "react";
import { RemoteConfigProvider } from "rn-remote-config";
import { MMKVStorage } from "./MMKVStorage";
import MainApp from "./MainApp";

const customStorage = new MMKVStorage();

export default function App() {
  return (
    <RemoteConfigProvider
      fallback={<Text>Loading Configuration...</Text>}
      options={{
        url: "https://api.example.com/remote-config.json",
        fetchPolicy: "cache-only-network-fallback",
        storage: customStorage, // 👈 Required storage injection
        loadCacheFirst: true, // Loads cached config instantly, updates from network in background
      }}
    >
      <MainApp />
    </RemoteConfigProvider>
  );
}

3. Use Remote Config Values in your Components

Use the reactive hooks to consume config values:

import React from "react";
import { View, Text } from "react-native";
import { useRemoteValue } from "rn-remote-config";

export default function MainApp() {
  // Subscribes reactively to the 'theme_color' key, uses '#000000' as fallback default
  const themeColor = useRemoteValue<string>("theme_color", "#000000");
  const isFeatureEnabled = useRemoteValue<boolean>("new_feature_enabled", false);

  return (
    <View style={{ backgroundColor: themeColor, flex: 1 }}>
      <Text>Remote Config values loaded!</Text>
      {isFeatureEnabled && <Text>New feature is enabled!</Text>}
    </View>
  );
}

API Reference

RemoteConfigProvider Props

| Prop | Type | Required | Description | | :--- | :--- | :---: | :--- | | children | React.ReactNode | Yes | The components that will have access to the remote configuration. | | fallback | React.ReactNode | Yes | UI to display while the configuration is loading (or if it fails and there is no cached data). | | options | RemoteConfigOptions | Yes | Configuration options for fetching and caching. | | onNetworkError | (error: any) => void | No | Callback triggered when the remote config network request fails. | | onConfigLoaded | (config: any) => void \| Promise<void> | No | Callback triggered when the configuration is successfully loaded (both on cache hits and network fetches). If a Promise is returned, the provider will await it before setting loading to false (hiding the fallback UI). |

RemoteConfigOptions

| Option | Type | Required | Default | Description | | :--- | :--- | :---: | :---: | :--- | | url | string | Yes | - | The HTTP endpoint where the remote configuration JSON resides. | | fetchPolicy | 'network-only' \| 'cache-only-network-fallback' | Yes | - | 'network-only': Always downloads from URL.'cache-only-network-fallback': Downloads, but falls back to cached data if the request fails. | | storage | IStorage | Yes | - | An instance implementing IStorage (e.g. MMKV or AsyncStorage wrapper). | | fetcher | IFetcher | No | HttpFetcher | Custom HTTP fetcher implementation. | | cacheKey | string | No | "remote-config" | The key under which the configuration is stored in the cache. | | loadCacheFirst | boolean | No | true | If true, the provider immediately loads the cached config on startup and updates it in the background. |

License

ISC