Building a Developer Debug Menu Into Your Rork App — Verify Ads, Purchases, and Remote Config Before Release

The Entrance — A Build Flag Plus the Seven-Tap Gesture

In an Expo project generated by Rork, the natural home for build-type declarations is app.config.ts. Receive a variant from the environment and enable debug features only for internal builds.

// app.config.ts — declare the variant in exactly one place
// EAS Build profiles pass APP_VARIANT (e.g. internal / production)
import { ExpoConfig } from "expo/config";
 
const variant = process.env.APP_VARIANT ?? "development";
 
const config: ExpoConfig = {
  name: variant === "production" ? "Beautiful Walls" : `Walls (${variant})`,
  slug: "beautiful-walls",
  extra: {
    appVariant: variant, // read at runtime via expo-constants
  },
  // ...rest of the config omitted
};
 
export default config;

At runtime, confine that value to a single predicate. Not reading Constants directly all over the codebase is exactly the anti-scatter measure from the previous section.

// src/debug/isDebugMenuAvailable.ts — the only entry point for the check
import Constants from "expo-constants";
 
const variant: string =
  Constants.expoConfig?.extra?.appVariant ?? "development";
 
// true only for development and internal; always false in production
export const isDebugMenuAvailable = (): boolean =>
  variant === "development" || variant === "internal";

For the entrance I use tap the version label seven times within three seconds. It mirrors the Android developer-options gesture, so testers need no explanation.

// src/debug/DebugGate.tsx — wired to the version label in settings
import { useRef, useCallback } from "react";
import { Pressable, Text } from "react-native";
import { router } from "expo-router";
import { isDebugMenuAvailable } from "./isDebugMenuAvailable";
 
const REQUIRED_TAPS = 7;
const WINDOW_MS = 3000; // 7 taps within 3 seconds
 
export function DebugGate({ version }: { version: string }) {
  const taps = useRef<number[]>([]);
 
  const onTap = useCallback(() => {
    if (!isDebugMenuAvailable()) return; // no-op in production
    const now = Date.now();
    taps.current = [...taps.current.filter((t) => now - t < WINDOW_MS), now];
    if (taps.current.length >= REQUIRED_TAPS) {
      taps.current = [];
      router.push("/debug"); // expo-router debug screen
    }
  }, []);
 
  return (
    <Pressable onPress={onTap} accessibilityLabel="app version">
      <Text>v{version}</Text>
    </Pressable>
  );
}

Expected behavior: on development and internal builds, seven taps open /debug; on production builds, nothing happens. And with the routing trick later in this article, production never even loads the module behind that route, so a deep link pointed at it simply lands on home.

The Menu Itself — Design Exactly One Override Layer

The menu screen is an ordinary settings list; nothing about it is interesting. The substance is the override store behind it. The key decision: keep real values (what production logic computes) and override values separate, and merge them at read time. If overrides mutate the real state directly, you can no longer guarantee that clearing an override restores reality.

// src/debug/debugOverrides.ts — an AsyncStorage-backed override store
import AsyncStorage from "@react-native-async-storage/async-storage";
 
export type DebugOverrides = {
  apiEnv?: "dev" | "staging" | "production";
  forceTestAds?: boolean;
  entitlement?: "none" | "adFree" | "premium";
  remoteConfig?: Record<string, string | number | boolean>;
  expiresAt?: number; // auto-expiry against forgotten overrides
};
 
const KEY = "debug.overrides.v1";
const TTL_MS = 24 * 60 * 60 * 1000; // expire after 24 hours
 
let cache: DebugOverrides = {};
 
export async function loadOverrides(): Promise<DebugOverrides> {
  const raw = await AsyncStorage.getItem(KEY);
  if (!raw) return (cache = {});
  const parsed: DebugOverrides = JSON.parse(raw);
  // discard when expired — so yesterday's overrides cannot ambush you today
  if (parsed.expiresAt && Date.now() > parsed.expiresAt) {
    await AsyncStorage.removeItem(KEY);
    return (cache = {});
  }
  return (cache = parsed);
}
 
export function getOverrides(): DebugOverrides {
  return cache; // synchronous read (loadOverrides runs at startup)
}
 
export async function setOverride<K extends keyof DebugOverrides>(
  key: K,
  value: DebugOverrides[K]
): Promise<void> {
  cache = { ...cache, [key]: value, expiresAt: Date.now() + TTL_MS };
  await AsyncStorage.setItem(KEY, JSON.stringify(cache));
}
 
export async function clearOverrides(): Promise<void> {
  cache = {};
  await AsyncStorage.removeItem(KEY);
}
 
export const hasActiveOverrides = (): boolean =>
  Object.keys(cache).some((k) => k !== "expiresAt");

The 24-hour expiresAt auto-expiry was added two weeks into running this, not designed up front. Whatever I override on a Friday night, Monday me has no memory of. Once I stopped designing around the assumption that I would remember, the recurring false alarm of wait, why is this still broken — oh, it is my own override — disappeared.

The badge that signals active overrides sits in the root layout.

// overlaid at the end of app/_layout.tsx (internal builds only)
{isDebugMenuAvailable() && hasActiveOverrides() && (
  <View pointerEvents="none" style={styles.debugBadge}>
    <Text style={styles.debugBadgeText}>OVERRIDE</Text>
  </View>
)}

Test-Ad Mode — Keep Your Real Ad Units Clean

In ad work, the scary failure mode is not a crash; it is policy. Show yourself real ads during development, tap one absent-mindedly, and you are generating invalid traffic that can put a warning on your AdMob account. The bulk of the 50 million cumulative downloads across my apps has been monetized on the free-plus-ads model, so the health of that AdMob account is, quite literally, the lifeline. That is why switching to test ads is one tap in the menu rather than something entrusted to a build flag.

// src/ads/adUnitIds.ts — ad unit resolution that respects overrides
import { TestIds } from "react-native-google-mobile-ads";
import { getOverrides } from "../debug/debugOverrides";
import { isDebugMenuAvailable } from "../debug/isDebugMenuAvailable";
 
const PRODUCTION_UNITS = {
  banner: "ca-app-pub-XXXXXXXXXXXXXXXX/NNNNNNNNNN", // inject real IDs from config
  interstitial: "ca-app-pub-XXXXXXXXXXXXXXXX/NNNNNNNNNN",
  rewarded: "ca-app-pub-XXXXXXXXXXXXXXXX/NNNNNNNNNN",
} as const;
 
type AdKind = keyof typeof PRODUCTION_UNITS;
 
export function resolveAdUnitId(kind: AdKind): string {
  // with forceTestAds on an internal build, return Google's official test IDs
  if (isDebugMenuAvailable() && getOverrides().forceTestAds) {
    const testIds: Record<AdKind, string> = {
      banner: TestIds.ADAPTIVE_BANNER,
      interstitial: TestIds.INTERSTITIAL,
      rewarded: TestIds.REWARDED,
    };
    return testIds[kind];
  }
  return PRODUCTION_UNITS[kind];
}

Besides the toggle, the ads section shows only the last five load results: which network filled, and what the error code was. During a stretch of mediation tuning, being able to read those five lines saved a full overnight round-trip of investigation more than once.

One more small habit: the badge changes color in test-ad mode (yellow for plain overrides, green while test ads are forced). It exists to prevent the inverse mistake — staring at eCPM while unknowingly still on test inventory.

Simulating Purchase State — Centralize the Check Before You Override It

The v2.1.0 bug from the opening was a composition gap in entitlements. Ad removal by one-time purchase lived in isAdFree; temporary ad removal earned by watching a rewarded ad lived in isRewardAdFree. A newly added paywall condition consulted only isAdFree. My own debug device had the purchase, so the bug was unreproducible at my desk — forever, by construction.

The lesson it left: make the check single-entry before making it overridable. While checks are scattered, no amount of override machinery closes every hole.

// src/entitlements/useEntitlements.ts — one merge point for real and override values
import { getOverrides } from "../debug/debugOverrides";
import { isDebugMenuAvailable } from "../debug/isDebugMenuAvailable";
import { usePurchaseState } from "./usePurchaseState"; // real purchase state
import { useRewardAdFree } from "./useRewardAdFree"; // temporary, earned by rewarded ads
 
export type Entitlements = {
  adFree: boolean;
  premium: boolean;
  source: "purchase" | "reward" | "debug" | "none";
};
 
export function useEntitlements(): Entitlements {
  const purchase = usePurchaseState();
  const rewardAdFree = useRewardAdFree();
 
  // debug overrides take top priority — and are not even evaluated outside internal builds
  if (isDebugMenuAvailable()) {
    const o = getOverrides().entitlement;
    if (o === "adFree") return { adFree: true, premium: false, source: "debug" };
    if (o === "premium") return { adFree: true, premium: true, source: "debug" };
    if (o === "none") return { adFree: false, premium: false, source: "debug" };
  }
 
  // merge real values — ad-free holds via either purchase or reward
  const adFree = purchase.adFree || rewardAdFree.active;
  return {
    adFree,
    premium: purchase.premium,
    source:
      purchase.adFree || purchase.premium
        ? "purchase"
        : rewardAdFree.active
          ? "reward"
          : "none",
  };
}

Returning source earns its keep quietly. The purchases section of the menu can display whether the current ad-free state comes from a purchase or from a reward, so a composition gap like the one above becomes visible at a glance instead of after two days of guessing.

For verifying modal behavior, I combine these overrides with the ModalGate pattern from My Paywall and Review Prompt Showed at the Same Time — Fixing It with a ModalGate Pattern. Being able to manipulate state (force premium) and triggers (force the paywall) independently is what flushes out priority bugs between competing modals.

Overriding Remote Config and Force-Firing Modals

Remote Config values propagate with a delay, and toggling them server-side while you verify client behavior is not a workable loop. Override on the client instead.

// src/config/remoteValue.ts — the single window onto Remote Config
import remoteConfig from "@react-native-firebase/remote-config";
import { getOverrides } from "../debug/debugOverrides";
import { isDebugMenuAvailable } from "../debug/isDebugMenuAvailable";
 
export function getRemoteValue<T extends string | number | boolean>(
  key: string,
  fallback: T
): T {
  // overrides win when present (internal builds only)
  if (isDebugMenuAvailable()) {
    const o = getOverrides().remoteConfig?.[key];
    if (o !== undefined) return o as T;
  }
  const v = remoteConfig().getValue(key);
  if (typeof fallback === "boolean") return v.asBoolean() as T;
  if (typeof fallback === "number") return v.asNumber() as T;
  return (v.asString() || fallback) as T;
}

Say you ship an interstitial frequency cap as interstitial_min_interval_sec: 90. Override it to 30 from the menu, walk through a few screens, and you have exercised the boundary behavior of your frequency control in minutes. When I was verifying a system that throttles ad load as crash rates rise, I overrode the threshold to fabricate a braking-engaged state on demand — the architecture itself is written up in Auto-Throttling AdMob When Crash Rates Spike: A Revenue-Protecting Brake Architecture with Rork, Firebase Remote Config, and Crashlytics.

Force-firing modals is nothing more than buttons that push entries straight onto the ModalGate queue. Make the three usual suspects — review prompt, paywall, announcement — stackable in any order, and you can reproduce on your desk a collision that natural conditions produce maybe once a month.

Removing It From Store Builds — Not Invisible, Absent

The finishing move. In production builds, do not merely hide the entrance; keep the code out of the bundle. I branch the expo-router route by variant so that in production the debug screen's module is never even required.

// app/debug.tsx — a route that never loads its content in production
import { Redirect } from "expo-router";
import { isDebugMenuAvailable } from "../src/debug/isDebugMenuAvailable";
 
export default function DebugRoute() {
  if (!isDebugMenuAvailable()) {
    return <Redirect href="/" />; // deep links bounce home
  }
  // lazy require — unreachable, and strippable, in production bundles
  const DebugMenu = require("../src/debug/DebugMenu").default;
  return <DebugMenu />;
}

One Expo-specific warning belongs here. Every environment variable prefixed EXPO_PUBLIC_ is embedded in the JS bundle in plain text. That property is what makes build-time branching optimizable, but it also means debug auth tokens or a staff-detection email list must never live there. Treat it as a place for values you would be comfortable publishing, because you are publishing them.

On review: App Store guidelines are strict about hidden functionality, and rather than argue interpretation, keeping the menu out of submitted builds entirely is the one stance with no ambiguity. My EAS Build profiles are split into production (store submission, no menu) and internal (TestFlight internal testing and Play internal track, menu included). And if I ever start a submission from the wrong configuration, the app.config.ts naming trick from earlier means the submission screen greets me with an app called Walls (internal). Putting the variant in the product name is a primitive tripwire, and it works precisely because it is primitive.

Pitfalls — The Ones I Actually Hit Across Six Apps

• Secrets in EXPO_PUBLIC_. As above: plain text in the bundle. Do not even put the debug menu passcode there. The correct protection is distribution scope — internal tracks only — not obfuscation.
• Stale overrides. Since pairing the 24-hour TTL with the always-on badge, override-induced false alarms have stayed at zero. Either measure alone eventually fails; the pair has not.
• Debug sessions polluting analytics. Impression events fired in test-ad mode quietly distort ARPDAU. My rule: while any override is active, every analytics event carries debug: true, and the pipeline filters them out. The event layer that makes that one-line change safe is described in Guarding Analytics Events With Types Across Six Rork Apps — A Shared Event Layer.
• Crossed EAS Update channels. Push an internal JS bundle to the production channel and your the code does not exist in production guarantee evaporates. I keep channel names identical to variant names and have the deploy script verify the pair before publishing; it has not happened since.
• Overrides surviving between internal builds. AsyncStorage overrides persist across app updates. Before testing version migrations, press Clear All at the bottom of the menu, every time. Production builds are safe regardless — isDebugMenuAvailable() is false there, so leftover values are never even evaluated.

Where to Start — A Variant Badge Is Enough

You do not need to build all of this at once. Declare the variant in app.config.ts and put a small internal badge in a corner of the screen. That alone removes the most basic anxiety of release verification — which build am I actually holding? From there, add menu items as real needs appear, and within a few weeks you will find you have grown a verification rig shaped exactly like your app.

If you have ever kept a release-build-only bug company past midnight, I hope this design shortens that night to an afternoon.