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](https://hotcfg.run/docs/guides/fetching), 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);
  }
}
```

## The gate

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](https://hotcfg.run/docs/guides/environments).

Last updated 10 November 2026
