Recipes

Maintenance mode for a React Native app

Show a maintenance screen in a React Native or Expo app during backend work, switched from a JSON file.

During a migration or an outage of your own backend, you want the app to show a friendly screen instead of failing request by request. Put the switch in a hotcfg bin and check it at launch and on every return to the foreground.

The config

maintenance.json
{
  "maintenance": {
    "enabled": false,
    "message": "We're upgrading our servers. Back in about 30 minutes."
  }
}

With a schema, so enabled can never be the string "false" (which is truthy in JavaScript):

schema.json
{
  "type": "object",
  "required": ["maintenance"],
  "properties": {
    "maintenance": {
      "type": "object",
      "required": ["enabled"],
      "properties": {
        "enabled": { "type": "boolean" },
        "message": { "type": "string", "maxLength": 300 }
      }
    }
  }
}
terminal
hotcfg bins create app-status --public
hotcfg push maintenance.json --bin app-status --env production

Fetching it

The browser fetch code, with AsyncStorage for the last good copy. It uses an AbortController timer rather than AbortSignal.timeout, which not every React Native version has.

remoteConfig.js
import AsyncStorage from "@react-native-async-storage/async-storage";

const URL = "https://api.hotcfg.run/v1/acme/app-status";
const DEFAULTS = { maintenance: { enabled: false } };
const KEY = "hotcfg.app-status";

export async function loadConfig() {
  const cached = JSON.parse((await AsyncStorage.getItem(KEY)) ?? "null");
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 2000);
  try {
    const res = await fetch(URL, {
      headers: cached?.etag ? { "If-None-Match": cached.etag } : {},
      signal: controller.signal,
    });
    if (res.status === 304 && cached) return cached.data;
    if (!res.ok) throw new Error(`hotcfg: ${res.status}`);
    const data = await res.json();
    await AsyncStorage.setItem(KEY, JSON.stringify({ etag: res.headers.get("ETag"), data }));
    return data;
  } catch {
    return cached?.data ?? DEFAULTS; // last good config, then bundled defaults
  } finally {
    clearTimeout(timer);
  }
}
MaintenanceGate.js
import { useEffect, useState } from "react";
import { AppState, Text, View } from "react-native";
import { loadConfig } from "./remoteConfig";

export function MaintenanceGate({ children }) {
  const [maintenance, setMaintenance] = useState(null);

  useEffect(() => {
    const refresh = () => loadConfig().then((c) => setMaintenance(c.maintenance ?? null));
    refresh();
    const sub = AppState.addEventListener("change", (s) => s === "active" && refresh());
    return () => sub.remove();
  }, []);

  if (maintenance?.enabled) {
    return (
      <View style={{ flex: 1, alignItems: "center", justifyContent: "center", padding: 24 }}>
        <Text style={{ fontSize: 18, textAlign: "center" }}>
          {maintenance.message ?? "We'll be right back."}
        </Text>
      </View>
    );
  }
  return children;
}

Wrap your app in it: <MaintenanceGate><App /></MaintenanceGate>. The app renders normally until the config says otherwise, so a slow network never shows a blank screen.

Switching it on and off

Edit maintenance.json and push, or flip enabled in the dashboard editor. When the work is done, hotcfg rollback app-status --env production --to <version> restores the version before. Practise first in staging with a staging build of the app; see Staging, promote and rollback.

Last updated 10 November 2026