DEV Community: Soham Mondal

How to Secure a Staging Environment With Google Cloud IAP

Soham Mondal — Tue, 01 Sep 2026 07:01:44 +0000

Every staging environment starts out reachable by anyone with the URL, and every team eventually notices that's a problem — a crawler indexes it, a support ticket links to it in public, an ex-employee's bookmark still works. The fix people reach for first is usually one of two extremes: a VPN nobody wants to run, or a login screen nobody wants to maintain. On Google Cloud there's a narrower option that costs almost nothing to turn on: Identity-Aware Proxy (IAP), a toggle on the load balancer that requires a verified Google identity before any request reaches the backend at all.

Point a browser at a protected URL, IAP bounces it through a Google login once, and a session cookie carries it for the rest of the day. For a browser-facing staging environment or internal tool, that's most of what "secure it" or "limit access to it" ends up meaning in practice — no VPN client to distribute, no user database to run, access that IAM already tracks. That ease is specific to browsers, though. The moment the client isn't one — a mobile app's embedded WebView, a CI job, a script hitting the same backend — IAP's contract changes completely, and it's worth knowing that cost before leaning on IAP for more than the browser case.

What IAP actually is

IAP (Identity-Aware Proxy)
A Google Cloud layer in front of a load balancer's backend service that requires a verified Google identity before any request reaches the backend. Toggled per backend service, not per URL path.

Mechanically, it's an auth check bolted onto GCLB (Google Cloud Load Balancer): a request hits the load balancer, IAP checks for a valid identity — a session cookie from a prior OAuth flow, or a bearer token with the right audience — and either lets the request through or bounces it into a Google sign-in flow. For a browser, that flow is a redirect and a cookie. For anything else, there's no redirect to follow and no cookie to hold.

Why teams reach for it

The appeal isn't the auth mechanism itself — OAuth redirects and session cookies are nothing new. It's what you don't have to build:

Staging and internal tools stay off the public internet without standing up a VPN or writing your own login layer.
Access rides on identities your org already has (Google Workspace), not a separate user database.
It's a toggle on an existing backend service, not another service to run, patch, and keep available.
Access is a list in IAM, not a config buried in application code — add or remove a person there, and it takes effect immediately, everywhere that backend is used.
Every access decision lands in Cloud Audit Logs, so "who hit staging and when" is a query, not an archaeology project.

For a browser-facing surface, that's close to free. The tax shows up somewhere else entirely.

Setting up IAP to limit access to staging

1. Enable IAP on a backend service. In the GCP console, under the load balancer's backend service, flip the IAP toggle. This is per backend service, not per URL path — anything routed to that backend is now gated.

2. Grant access. Under IAM, add the principals (individual users, a Google group, or a service account) that should get through, with the IAP-Secured Web App User role. Nothing else grants access — being a project owner doesn't bypass IAP.

3. Verify the browser flow. Hit the protected URL in a browser as a granted principal — expect the Google sign-in redirect once, then normal access.

4. Get a token for a non-browser client. For a quick manual test, gcloud auth print-identity-token --audiences=<IAP_CLIENT_ID> mints a token you can attach directly. In an app, that's a service-account-signed JWT or an OIDC client credential exchange instead, but the shape of the request is the same either way:

# Without a token: IAP redirects to the login page
curl -i https://stage.example.com/

# With a correctly-audienced bearer token: passes straight through
curl -i -H "Authorization: Bearer $(gcloud auth print-identity-token --audiences=$IAP_CLIENT_ID)" \
  https://stage.example.com/

If a browser is the only client that needs through, that's the whole setup. If a mobile app, a CI job, or a script also needs to reach the same backend, the next section is the real cost of that — worth reading before assuming IAP covers those the same way it covers a browser tab.

Where it stops being invisible: web vs. non-browser clients

On the web, the free lunch is real: no client code, no token management, a cookie the browser already knows how to carry. The one thing worth knowing is that it's still an interactive flow — anything that can't render a redirect and complete a Google login (headless browsers, most testing tools) hits the same wall a non-browser client does.

Off the web, none of that machinery exists. IAP doesn't issue a session cookie for token-based auth — there's nothing to persist, nothing to keep warm. A non-browser client has to attach a bearer ID token to every request it wants to get through, and that's where the actual complexity of "add IAP" lives. Four things commonly go wrong, in roughly the order teams find them:

The wrong header wins. Proxy-Authorization is the technically correct header for talking to an intermediary like IAP — it's meant to be stripped before the request reaches your own backend. In practice, GCLB's IAP implementation doesn't reliably honor it, and on Android, WebViews reject it outright on document requests (ERR_INVALID_ARGUMENT). What actually works is Authorization — the same header slot most apps already use for their own session. That's an awkward collision, not an elegant design; it's just what's left once the "correct" option turns out not to work reliably.

// Attach the IAP token only to the initial document load
const source = {
  uri: stageUrl,
  headers: iapToken ? { Authorization: `Bearer ${iapToken}` } : undefined,
};

The token has the wrong audience. A client library's default sign-in call often hands back an ID token scoped to itself — "this is the mobile app" — not to IAP. Send that one and IAP rejects it with an audience mismatch, even though the token is valid, signed, and unexpired. The token that clears IAP has to be requested separately and checked before it's trusted:

private async requestAndCacheToken(): Promise<boolean> {
  try {
    this.token = await this.requestToken(); // the IAP-audience token, not the default sign-in one
    if (this.token && decodeAud(this.token) !== IAP_CLIENT_ID) {
      // cached session, wrong audience — force re-auth instead of trusting it
      await this.reauthenticate();
      return this.requestAndCacheToken();
    }
    this.notify(this.token);
    return Boolean(this.token);
  } catch (error) {
    captureException('[IAPAuthClient] token fetch failed', error);
    this.notify(null);
    return false;
  }
}

aud vs. azp
Both show up in an OIDC token and look interchangeable until a request gets rejected. aud is who the token is for — what IAP checks against its allowlisted clients. azp is who actually requested it — the client's own identity. Mixing them up produces a token that's completely valid and still gets bounced.

Everything the header doesn't reach still goes through IAP. A bearer token on the document request only covers that one request. Every automatic follow-up request a page makes — <script src>, stylesheets, fonts — hits the same IAP-protected backend with no header attached, gets redirected to the Google login page, and comes back as HTML. Browsers then hit X-Content-Type-Options: nosniff, refuse to execute HTML as JavaScript, and the page just... stops. No error, no crash, just a static shell that never hydrates.

X-Content-Type-Options: nosniff
Tells the browser not to guess a resource's type from its content. When IAP swaps a JS file for an HTML login page, this header is what stops the browser from quietly trying to run HTML as a script — it refuses instead, silently.

There's no client-side fix for this — a <script> tag's request can't carry a custom header. The actual fix is infrastructural: serve static assets from a second backend service that isn't behind IAP at all, the same pattern most production setups already use for CDN-hosted, content-hashed bundles. Since IAP toggles per backend service and not per URL path, this means standing up a second backend and a URL-map split, not flipping a flag.

sequenceDiagram
    participant Client
    participant IAP as IAP-gated LB
    participant Bypass as Non-IAP backend
    Client->>IAP: GET /page  (Authorization: Bearer <token, aud=IAP client>)
    IAP-->>Client: 200 HTML shell
    Client->>Bypass: GET /dist/app.bundle.js  (no header)
    Bypass-->>Client: 200 application/javascript
    Note over Client: page hydrates normally

The client fan-out cost. Every environment an OAuth client needs to reach IAP for is its own client registration — and on Android, its own SHA-1 fingerprint per signing key. Give every stage tier its own bundle ID and you're registering a client (and, per developer, a debug-keystore fingerprint) for every environment × every machine. That stops scaling past a handful of people fast. Teams that hit this usually collapse it the same way: one non-prod build with a runtime environment picker instead of a build-time bundle ID per tier, so the OAuth client count stays fixed regardless of how many stage environments exist.

flowchart LR
    A[EnvironmentPicker: pick backend] --> B[persist choice]
    B --> C[hydrateRuntimeConfig on boot]
    C --> D["config.* resolves to selected preset\n(webview URL, IAP client, feature flags)"]
    D --> E[AuthGate: does this preset need IAP?]
    E -->|yes| F[Google sign-in -> IAP token]
    E -->|no| G[skip straight through]

Two smaller gotchas round this out, both specific to embedding a web page inside a native WebView rather than to IAP itself: cookies leaking in from the native app's own API calls can corrupt the page's hydration state (fixed by running the WebView incognito, with sharedCookiesEnabled={false}), and naively remounting the WebView to reapply the header on navigation cancels every in-flight tap, not just the one redirect it meant to catch — the fix is swapping source in place instead of remounting.

<GatedWebView
  incognito
  sharedCookiesEnabled={false}
  source={source}
  onNavigationStateChange={handleNavigationStateChange}
/>

Put together, that's a real amount of work to make a non-browser client behave like a browser IAP was designed for. It's worth asking, before signing up for it, whether the non-browser client needs to talk to the IAP-gated backend at all. If most of that access is internal — a CI job hitting staging, a build script, a developer's local tooling — a short-lived service-account token issued at build time, or just a VPN, is often simpler than teaching every client to carry a bearer token correctly. IAP earns its keep when the end user needs individually attributable, revocable access. It's a heavier tool than necessary for access that's really "this machine is allowed to talk to that machine."

Alternatives to IAP

IAP isn't the only way to gate a backend behind identity — worth knowing what else is on the table before committing to it:

Cloudflare Access — the same shape as IAP (edge proxy, OAuth redirect, per-request policy), but at Cloudflare's edge instead of GCLB, and not tied to GCP.
Tailscale / Tailscale Funnel — network-level identity over WireGuard; a client joins the tailnet once instead of carrying a token per request, which removes the header/audience problems entirely, at the cost of every client needing the Tailscale client installed.
AWS ALB + Cognito — the AWS-native equivalent of the same redirect-and-cookie pattern, for teams already on that load balancer.
A plain VPN — gates at the network layer, completely invisible to the application; simple for internal-only, non-browser access, but the VPN client itself becomes the thing every user and machine has to run.
mTLS — certificate-based, and uniform across browser and non-browser clients since there's no OAuth redirect involved at all; the cost moves to certificate distribution and rotation instead.
A custom JWT-checking middleware — full control over the token shape and validation logic, and full ownership of maintaining it, which is exactly the auth layer IAP exists to let you skip.

The deciding question is usually whether your non-browser clients can tolerate a redirect-based flow at all. If they can, IAP or Cloudflare Access are the least amount of new infrastructure. If they can't — or if the access is really machine-to-machine — a VPN, Tailscale, or mTLS avoids the token dance altogether.

Closing

Securing a staging environment usually just means keeping it off the open internet while letting the right people straight through, and for a browser-facing surface, IAP does that with a toggle and an IAM entry instead of a service you have to run. It stops being free the moment a non-browser client needs through — budget for that as a real cost, not a footnote, and check first whether that client actually needs individually-attributable access at all, or just network-level access a simpler tool already provides.

Composition Over Configuration Is a Rule I Keep Re-Deriving

Soham Mondal — Tue, 01 Sep 2026 06:59:13 +0000

Every settings page in a growing app ends up with a modal that opens for profile info, or billing, or notification preferences, whatever product asked for last sprint. The lazy way to build that is one modal component with a section prop:

export type SettingsSection = 'profile' | 'billing' | 'notifications';

export type SettingsPanelChrome = {
  title?: string;
  size?: 'compact' | 'wide';
  dismissible?: boolean;
};

export interface SettingsModalProps {
  section: SettingsSection | null;
  onClose: () => void;
  chrome: Record<SettingsSection, SettingsPanelChrome>;
  footer: React.ReactNode;
  children: (active: SettingsSection) => React.ReactNode;
}

That's roughly the shape a settings modal takes the first time someone builds it, before a refactor forces the issue. It looks reasonable. It compiles. It even feels DRY — one modal, one footer, one set of chrome rules, reused across every section. The catch shows up the next time product asks for a fourth section: you touch the section union, you touch the chrome record, you touch the children discriminator inside the modal, and you touch whatever component was rendering based on active. Four call sites for one new section, all inside a component that was supposed to be generic.

I keep running into this shape and keep tearing it back out. Not as a one-off cleanup — as a rule I apparently have to re-derive every few weeks, because the config-object version is always the one that gets written first.

The anti-pattern, defined once

A shared component that switches on a string or union discriminator — mode, type, variant — with a config map keyed by that same discriminator sitting next to it. New variant means editing the component that was supposed to be closed for modification. It reads like reuse. It's actually coupling: every variant now depends on the shared dispatcher knowing about it by name.

Case one: the settings-modal god-component

A modal-and-nav pair built around that section discriminator and a chrome record supplying per-section titles and sizing had grown to a few hundred lines before I replaced both with one self-contained component per section — ProfileSettings, BillingSettings, NotificationSettings — each owning its own modal ref, its own content, its own footer:

export const ProfileSettings: React.FC = () => {
  const modalRef = React.useRef<ModalHandle>(null);
  const { profile, updateProfile, saveProfile } = useProfileForm();

  return (
    <>
      <SettingsNavItem
        label="Profile"
        icon={UserIcon}
        isActive={false}
        onPress={() => modalRef.current?.open()}
      />
      <Modal ref={modalRef}>
        <ProfileForm value={profile} onChange={updateProfile} />
        <SaveButton onPress={saveProfile} />
      </Modal>
    </>
  );
};

The nav itself became a plain composition root:

export const AccountSettings: React.FC = () => (
  <SettingsNav>
    <ProfileSettings />
    <BillingSettings />
    <NotificationSettings />
  </SettingsNav>
);

A fourth section now means writing a fourth file and adding one line to that list. Nothing else moves.

The payoff isn't just fewer files touched per new section — it's that AccountSettings can now be recomposed per surface without anyone touching a settings component. A support-tools screen that only needs billing and notifications doesn't need a visibleSections prop threaded through the old modal; it just renders fewer children:

export const SupportToolsSettings: React.FC = () => (
  <SettingsNav>
    <BillingSettings />
    <NotificationSettings />
  </SettingsNav>
);

That's the actual argument for composition over configuration, not just the tidier one: a config object can only do what its author anticipated (add a visibleSections array, thread it through every layer, remember to keep it in sync). A tree of components can be rearranged by anyone, from outside, without touching the pieces being rearranged.

The nav item that sits in that list had its own smaller version of the same disease — a hand-rolled props type duplicating fields the design system's Tab already exposed. I fixed that the same day, by picking from the library type instead of re-declaring it:

export type SettingsNavItemProps = Pick<
  TabProps,
  'icon' | 'badge' | 'onPress' | 'disabled'
> & {
  label: string;
  isActive: boolean;
};

That's a narrower version of the same instinct: don't build your own config shape when a real one already exists next to you.

Composition root
A component whose only job is to arrange other components — no branching, no business logic, no shared state of its own. AccountSettings above is one: it decides which sections exist, not how any single section behaves.

That's the whole shape of the fix: three small things a caller can point at directly, instead of one thing a caller has to configure correctly.

The part that made it stick

Fixing the god-component once doesn't stop the next PR from reaching for a section prop again — it's the cheapest thing to write under deadline, and it compiles cleanly the first time. So in the same change that shipped the breakup, I also wrote down the judgment call as a rule file the AI coding agent reads before it touches this part of the codebase again — roughly:

---
description: "Split shared containers that branch on a mode/type/variant prop into one self-contained component per variant"
globs: "**/*.tsx"
---

# Composition over configuration

If a component picks its content, footer, or layout based on a
discriminator prop, that's a sign the variants should be separate
components instead. Give each variant its own trigger, its own
content, its own actions, and let the parent just arrange them.

Not a wiki page — something the agent actually reads before it writes the next settings component. That's the whole judgment call, captured once so it doesn't depend on me remembering it three PRs from now.

Case two: the union that grew back two weeks later

Two weeks after the settings-modal cleanup, I was back in the same feature area rewriting the toggle primitives underneath it, and the same shape had regrown somewhere else. The shared toggle option type carried two ways to produce a label:

export type ToggleOptionLabel = { text: string } | { render: () => React.ReactNode };

export const resolveLabel = (label: ToggleOptionLabel) =>
  'text' in label ? label.text : label.render();

Every toggle using the shared option type — a dozen of them, across profile, billing, and notification preferences — had to import resolveLabel and call it before rendering. A branch inside a mapper, fanned out across a dozen call sites, to solve a problem that didn't need solving: every option in practice just needed a plain string. The render branch existed for a customization case that, once I actually checked, no call site used.

I deleted the label-union type and the resolver — a customization escape hatch nobody had reached for — and gave the toggle a single field:

export type ToggleOption<Value extends string> = {
  value: Value;
  label: string;
  Icon?: ToggleIconComponent;
};

export const ToggleOption: React.FC<ToggleOptionProps> = ({ label, ...props }) => (
  <ToggleButton {...props}>{label}</ToggleButton>
);

Every call site got simpler in the same diff:

const NOTIFICATION_OPTIONS: ToggleOption<NotificationChannel>[] = [
  { value: NotificationChannel.EMAIL, label: 'Email', Icon: Mail },
  { value: NotificationChannel.PUSH, label: 'Push', Icon: Bell },
];

I didn't think of this as a bugfix or a cleanup while I was doing it. Looking back at the diff afterward, it was plainly just replacing a config builder with direct composition — fewer files, fewer indirections, the same behavior.

The same change did the mirror-image version of the fix on the compound component wrapping every settings group. It used to take a contentSpacing?: 'compact' | 'regular' prop and switch internally:

const Content = ({ children, spacing = 'regular' }) => (
  <div className={spacing === 'compact' ? 'content-compact' : 'content-regular'}>
    {children}
  </div>
);

That's the same discriminator problem in miniature — a config flag deciding which style branch runs inside one shared node. I split it into two real leaves instead of one leaf with a mode switch:

const Content = ({ children }) => <div className="content-regular">{children}</div>;
const CompactContent = ({ children }) => <div className="content-compact">{children}</div>;

export const SettingsGroup = List as SettingsGroupComponent;
SettingsGroup.Content = Content;
SettingsGroup.CompactContent = CompactContent;

Callers now write <SettingsGroup.CompactContent> when they want compact spacing, instead of passing a flag into a component that decides for them. Composition over configuration cuts both ways: sometimes it means deleting a union, sometimes it means turning a config prop into an actual leaf a caller can choose.

The rule, stated plainly

Neither fix was hard once I saw it. What's consistent is that I didn't see either one the first time a config object got written — I saw it weeks later, once a second variant made the branching visibly expensive. A mode prop with one value is invisible; with two, it still looks cheaper than two new files. It only starts looking wrong around the third or fourth branch, by which point it's load-bearing for every call site depending on it.

If two variants share most of their behavior, that's not evidence they should be one component with a switch — it's evidence they'll fork eventually, and the switch just defers the fork to a worse moment. Two small self-contained things, composed by a thin parent, beats one configurable thing almost every time the second variant is real rather than hypothetical. That's why a rule file earns its keep here in a way a PR comment doesn't: a comment fixes the diff in front of you; a rule file gets read the next time an agent — or me, a few weeks from now — is about to write the fifth branch of a config map, before it exists to comment on.

I still expect to re-derive this on some other screen. That's fine — the rule file just needs to catch it faster next time, not make sure I never write a mode prop again.

Why My React App Still Runs on Singleton Classes

Soham Mondal — Tue, 01 Sep 2026 06:55:01 +0000

React spent the last decade training developers that a class is a code smell. Class components got deprecated, hooks won, and "just write a function" became the default advice for almost everything. That advice runs into a wall the moment a piece of code has to run outside a component: an HTTP interceptor, an event listener, a background task, a deep-link handler. None of those have a render tree to sit inside, which means none of them can call a hook.

That's not a style opinion. It's a hard constraint. It's also the reason core pieces of infrastructure in most non-trivial React codebases — auth tokens, feature flags, routing rules, device identity, analytics — end up as classes, usually singletons, imported directly instead of consumed through a hook or a context provider.

The render-tree boundary problem

A hook only exists while its component exists. useState allocates memory tied to a place in React's tree; the moment that component unmounts, the state is gone, and before it mounts, the state isn't reachable at all. That's fine for almost everything a component owns. It stops being fine the moment something outside the tree needs the same piece of state.

Authentication is the clearest version of this. A typical setup keeps the access token in a hook, refreshed on a timer, exposed to whatever component needs it:

export const useSessionTokens = (): UseSessionTokens => {
  const [tokens, setTokens] = React.useState<AuthTokens | null>(null);

  const refreshAccessToken = async () => {
    if (!tokens?.refreshToken) return;
    const newTokens = await refreshAndSetTokens({ refreshToken: tokens.refreshToken });
    setTokens(newTokens);
    return newTokens;
  };
  // ...
  return { tokens, refreshAccessToken, /* ... */ };
};

Perfectly normal hook. The problem shows up one layer down: an HTTP client's request interceptor is a plain function, registered once at app boot, running completely outside React's render tree. It can't call useSessionTokens() — it isn't a component, and never will be. Whatever token that hook is holding in memory is invisible to it.

A synchronous, shared source of truth

Without access to the hook's in-memory value, the interceptor's only remaining option is to go around it — read the token from wherever it was last persisted, on every single outgoing request:

export const requestInterceptor = async (config: InternalAxiosRequestConfig) => {
  const accessToken = await secureTokenStore.getAccessTokenAsync();
  if (!accessToken) return config;

  if (isTokenValid(accessToken)) {
    config.headers.Authorization = `Bearer ${accessToken}`;
  }
  // ...
};

That's a secure-storage round-trip on every request, not because the app doesn't already have the token in memory, but because the place holding it is locked inside a React tree the interceptor lives outside of.

The fix is to move the token out of the hook and into a class that isn't tied to any component's lifecycle:

export class SessionTokenManager {
  private static instance: SessionTokenManager | undefined;
  private tokens: AuthTokens | null = null;

  private constructor() {
    this.appLifecycle = AppLifecycleObserver.getInstance();
    this.setupAppLifecycleListener();
  }

  static getInstance(): SessionTokenManager {
    if (!this.instance) {
      this.instance = new SessionTokenManager();
    }
    return this.instance;
  }

  getTokens() {
    return this.tokens;
  }
  // ...
}

getTokens() is synchronous. No await, no secure-storage call, no dependency on where in the tree the caller happens to be standing. The interceptor calls it directly:

export const requestInterceptor = async (config: InternalAxiosRequestConfig) => {
  const sessionTokenManager = SessionTokenManager.getInstance();
  const tokens = sessionTokenManager.getTokens();
  if (!tokens?.accessToken) return config;
  if (isTokenValid(tokens.accessToken)) {
    config.headers.Authorization = `Bearer ${tokens.accessToken}`;
  }
  // ...
};

So does the auth provider, memoizing the same instance so React doesn't re-fetch it every render:

const sessionTokenManager = React.useMemo(() => SessionTokenManager.getInstance(), []);

So does any component several layers deep that needs an auth header and has no reason to thread that dependency through props — it just calls SessionTokenManager.getInstance().getTokens() directly.

No prop drilling, no context provider, and — the part that actually matters — one shared source of truth instead of separate code paths that could each independently decide the token was stale.

Why private constructor + getInstance() instead of just new SessionTokenManager()
A private constructor makes "there is exactly one of these" a compile error, not a convention. Nothing can accidentally instantiate a second SessionTokenManager with its own stale copy of the tokens and its own refresh timer running independently of the first one.

When branching logic needs one shared entry point

The token manager solves a state problem. The same reasoning applies to a control-flow problem: deciding whether a route is even allowed to render.

A common shape for that starts as one function with a growing pile of nested if statements, one per guard:

export const resolveRouteGuard = ({ pathname, session, featureFlags }) => {
  if (!session?.isAuthenticated && !PUBLIC_ROUTES.includes(pathname)) {
    return { redirectTo: '/login' };
  }
  if (session?.isAuthenticated && !session.hasCompletedOnboarding && pathname !== '/onboarding') {
    return { redirectTo: '/onboarding' };
  }
  // then feature-flag gates, then maintenance mode, then role checks...
  return null;
};

Every new guard means another if block in a function that already has five reasons to change, and each one has to be careful not to trip over the guards ordered before it — swap two of these ifs and a logged-out user can land on the onboarding screen instead of the login screen. Testing one guard means faking enough state to get past every earlier if first. Replacing that function with an abstract class and one subclass per guard fixes both problems at once:

export abstract class RouteGuard {
  abstract shouldHandle(context: RouteContext): boolean;
  abstract handle(context: RouteContext): RouteOutcome;
}

export class AuthGuard extends RouteGuard {
  shouldHandle(context: RouteContext): boolean {
    return !context.session?.isAuthenticated && !PUBLIC_ROUTES.includes(context.pathname);
  }

  handle(): RouteOutcome {
    return { redirectTo: '/login' };
  }
}

And a runner that knows nothing about auth, onboarding, or feature flags — it just walks the list:

export class RouteGuardRunner {
  constructor(private guards: RouteGuard[]) {}

  resolve(pathname: string, session: Session, featureFlags: FeatureFlags): RouteOutcome | null {
    const context = this.buildContext(pathname, session, featureFlags);
    for (const guard of this.guards) {
      if (guard.shouldHandle(context)) return guard.handle(context);
    }
    return null;
  }
}

const routeGuardRunner = new RouteGuardRunner([
  new AuthGuard(),
  new OnboardingGuard(),
  new FeatureFlagGuard(),
  new MaintenanceModeGuard(),
]);

Chain of responsibility
Each guard decides independently whether it applies (shouldHandle) and, if so, what to do about it (handle). The caller never branches on guard type — it just asks each one in order and stops at the first match. That turns "one function that knows about four guards" into "four files that each know about one," and each guard gets its own test file, testable without faking the other three guards' preconditions first.

The same shape shows up anywhere a chain of independent, ordered checks needs to run — resolving an incoming deep link to the right screen, or dispatching a webhook payload to the right handler, is a near-identical problem wearing different names. Once a pattern like this exists in a codebase, copying the working shape is cheaper than re-deriving one from a fresh pile of if statements the next time a similar problem shows up.

When to reach for it

None of this is really about the class keyword, and it isn't an argument for OOP as a philosophy. It's about recognizing when a piece of code has to keep working outside the boundaries React manages automatically. Three conditions are the actual trigger.

The code has to run outside the render tree. An interceptor, an event listener, a deep-link handler, a background task — anything registered once at boot and invoked independently of whether a component is currently mounted.

Several unrelated call sites need to agree on one shared, mutable value. If three different files can each independently decide a token is stale, or start their own refresh timer, that's effectively a race condition with extra steps.

The code wraps a third-party SDK that already has its own imperative lifecycle. A remote-config SDK, an analytics SDK, a native module bridge — these come with their own init() / subscribe() / teardown, and forcing that lifecycle through useEffect usually means fighting the SDK instead of using it.

A device-identity service is a compact example of the first and third conditions together: it generates a random ID once on first install and has to reuse it forever, and initialize() has to be safe to call from multiple places at boot without a race creating two different IDs. The fix is a private initializationPromise field — concurrent callers await the same in-flight write instead of each kicking off their own. A bare exported initializeDeviceId() function could do the same thing, but only by smuggling that promise into a module-level variable — at which point it's a class with extra steps and no private keyword stopping some other file from reading or resetting it by accident.

Enforced vs. conventional singletons

Not every singleton enforces its own uniqueness the same way, and the difference is worth being precise about.

SessionTokenManager and the device-identity service use a private constructor and static getInstance() — the compiler physically stops anything from writing new SessionTokenManager() a second time. Clients that wrap an already-singleton third-party SDK usually skip that:

export class FeatureConfigClient {
  constructor() {
    this.instance = getRemoteConfig();
  }
  // ...
}

export const featureConfig = new FeatureConfigClient();

Just a plain constructor, instantiated once at module scope, exported as a const — the same shape an analytics client or an attribution client gets. Nothing stops another file from writing new FeatureConfigClient() — it's a convention, not a guarantee. That's a deliberate downgrade from the enforced version, and usually the right call: these clients wrap SDKs that are already global singletons under the hood, so a second instance would be redundant rather than dangerous. The token manager gets the stricter treatment because a second instance really would drift — its own refresh timer, its own in-memory copy of tokens that could disagree with the first one about whether the user is even logged in.

Enforced vs. conventional
Reach for the enforced version (private constructor + getInstance()) when a second instance would cause real drift — separate timers, separate in-memory state that can disagree with the first. Reach for the conventional version (plain constructor, instantiated once at module scope) when the class is a thin wrapper around something that's already a singleton elsewhere, like a third-party SDK — the guarantee already exists one layer down, so enforcing it again is just ceremony.

A comment worth stealing, usually sitting near a context provider in codebases that get this right, says the rule out loud better than a paragraph can:

// Context holds only reactive state — stable clients are module-level singletons
// imported directly: `import { analyticsClient } from 'core/analytics'`

Context should carry only the couple of values that actually change and that components need to re-render on — an anonymous ID, an attribution ID. The SDK clients themselves never go through context: there's nothing reactive about them, so putting one there just means every consumer pays a useContext subscription for a value that's never going to change out from under them.

The tradeoffs

These wins aren't free, and the costs are worth naming plainly instead of only selling the upside.

Testing gets harder. A hook resets itself for free between test runs — a new render, a new useState. A singleton doesn't. If a test calls SessionTokenManager.getInstance() and mutates it, every test that runs afterward inherits that state unless something explicitly resets .instance to undefined between runs — usually a resetInstance() method or a beforeEach block. Skip that and the failure doesn't show up loudly: tests pass in isolation and fail only when run together, because they're all sharing one instance's leftover state.

There's no automatic cleanup. A hook's useEffect return function runs on unmount, for free, every time. A singleton has no unmount — if it holds a timer, a subscription, or a listener, something has to remember to tear it down explicitly, and there's no lifecycle event that guarantees that will happen.

It's easy to overuse. The same properties that make a singleton useful for a token manager — global reachability, no need to thread it through props — make it just as easy to reach for when the real fix is a context provider or just lifting state up. A codebase where every shared value quietly becomes a singleton loses the thing React's data flow is supposed to provide: the ability to look at a component and know where its data comes from.

That's not an argument for bringing back class components — most of a React app should still be function components, and most shared logic should still be a hook. Reach for a class, and consider making it a singleton, only when the three conditions above actually apply. What decides it, every time, is whether the thing needs to still be there when no component is rendering: SessionTokenManager.getInstance() exists before the first screen mounts and after the last one unmounts, because whatever depends on it doesn't care whether anything is currently on screen.

How We Keep a Trunk-Based Pipeline From Being Reckless

Soham Mondal — Tue, 25 Aug 2026 18:52:20 +0000

Part 1 covered the routing decision: the orchestrator checks the native fingerprint and decides whether a release can go out as an OTA update or needs a new binary. Useful, but incomplete. A gate that answers "is this runtime-compatible" says nothing about whether the change is actually good.

That is the part people get wrong when they hear "we ship from main." They picture chaos. What they should picture is a stricter PR gate, heavier feature-flag discipline, and a hotfix path that is more explicit than the git-flow version ever was.

If every merge to main can theoretically reach production in minutes, then the safety net cannot be "we'll probably notice something during the release train." The safety has to live inside the pipeline.

Trunk-based is not lower process
It is lower branch ceremony and higher automation discipline. If your test gate, flags, and hotfix routing are weak, trunk-based will expose that fast.

The PR gate

Every pull request into main runs through the same automated gate before it is mergeable: typecheck, lint, test suite, and end-to-end checks. None of that is negotiable. That is the floor.

The exact tools matter less than the contract. A PR should not become releasable because a reviewer felt good about it. It should become releasable because the same mechanical checks passed every other healthy change before it.

That gate usually looks boring, which is good:

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run typecheck

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test -- --runInBand

  e2e:
    runs-on: ubuntu-latest
    needs: [typecheck, lint, test]
    steps:
      - uses: actions/checkout@v4
      - run: npm run e2e

Nothing exotic under the hood: ESLint, Jest, React Native Testing Library, whatever your E2E layer is, plus local hooks so the obvious failures get caught before CI has to. Popular, boring, well-documented tooling on purpose. The value is not in a fancy test stack. The value is that main has a contract.

The contract is simple: if a change lands, it is expected to be shippable.

That does not mean every merge must go live instantly. It means the system should not depend on a separate stabilization branch to discover obvious breakage later.

Feature flags are the real safety valve

Here is the rule that makes OTA-from-main survivable at all: shipping code and releasing a feature are two different actions.

A merge can put code on devices within minutes. Whether users can actually hit that code path is a separate decision, controlled remotely.

That decoupling is what makes trunk-based development workable for product teams. Nobody has to merge at the exact perfect moment. "Merged" does not have to mean "visible."

Deploy vs release
Deploy means the code is present on user devices. Release means users can actually experience it. In a healthy mobile pipeline, feature flags let you separate those two decisions.

const enabled = await featureFlags.isEnabled('new_checkout_flow', {
  userId,
  platform,
  appVersion,
});

if (enabled) {
  return <NewCheckoutFlow />;
}

return <LegacyCheckoutFlow />;

Anything not ready to be user-visible goes behind a flag before it goes near main: half-finished work, risky rewrites, migrations, pricing experiments, staged onboarding changes, whatever.

That is not a code review nit. That is release architecture.

I've used both Firebase Remote Config and Flagsmith for this in production. Different tradeoffs, same core job. Firebase is convenient if you're already deep in that ecosystem and need straightforward targeting. Flagsmith gives you a bit more explicit control once flags start becoming part of how the team routinely operates. Either is fine. What matters is not the vendor. What matters is whether the team actually treats flags as the release valve instead of an occasional convenience.

One simple pattern that ages well is keeping the risky decision point in one place:

export async function shouldRenderNewCheckout(ctx: {
  userId: string;
  platform: "ios" | "android";
  appVersion: string;
}) {
  return featureFlags.isEnabled("new_checkout_flow", {
    userId: ctx.userId,
    platform: ctx.platform,
    appVersion: ctx.appVersion,
  });
}

That looks small, but centralizing flag evaluation pays off later when you need percentage rollouts, kill switches, environment-aware defaults, or analytics around who saw what.

The same fingerprint gate, wearing a different hat

The fingerprint check from Part 1 is not just an OTA router. It is also what makes hotfix routing sane.

Because the gate compares against the exact binary currently in the store, the system always knows one thing with certainty: whether main could safely reach the devices that are live right now, or whether it has drifted natively since the last binary release.

That single fact matters a lot during an incident. It answers the first question fast: can we fix this on top of the current trunk, or do we need to cut from the live snapshot?

Hotfixing without touching `main`

A production fire needs a fix routed to wherever users actually are. After a few routine OTAs, that is often not the same commit as the last full store release. So the pipeline keeps immutable reference points for what is live.

Two protected snapshots exist for exactly this:

One pinned at the last full store release.
One pinned at the last successful OTA, if a newer one shipped since.

A hotfix branches off whichever of those two is actually live, ships from there, and only afterward gets merged or cherry-picked forward into main.

Neither snapshot branch is a development branch. They are frozen markers. That is what keeps a hotfix from accidentally dragging in unrelated work that landed on main after the last production-safe point.

In practice, the routing logic is this plain:

flowchart TD
    A([Production issue found]) --> B{Does main match the live runtime?}
    B -->|Yes| C[Fix on main]
    C --> D{Fingerprint still matches?}
    D -->|Yes| E[Publish OTA]
    D -->|No| F[Cut full release]
    B -->|No| G[Branch from live snapshot]
    G --> H[Patch only what is needed]
    H --> I{Fingerprint matches snapshot runtime?}
    I -->|Yes| J[Ship hotfix OTA]
    I -->|No| K[Build and submit hotfix binary]
    J --> L[Merge forward into main]
    K --> L
    E --> M([Users receive fix])
    F --> M
    L --> M

    classDef start fill:#f4e1bd,stroke:#171717,color:#171717,stroke-width:2px;
    classDef normal fill:#fffaf2,stroke:#171717,color:#171717,stroke-width:2px;
    classDef decision fill:#efe6d8,stroke:#171717,color:#171717,stroke-width:2px;
    classDef action fill:#f7f1e8,stroke:#171717,color:#171717,stroke-width:2px;
    classDef release fill:#f0b35f,stroke:#171717,color:#171717,stroke-width:2px;

    class A,M start;
    class B,D,I decision;
    class C,G,H,L normal;
    class E,F,J,K release;

There is no heroism in this. That is why it works.

The whole shape of it

None of these pieces does much on its own.

The PR gate keeps obvious breakage out.
Feature flags decouple deploy from release.
The fingerprint check protects the native/runtime boundary.
Snapshot branches make hotfix routing explicit instead of improvisational.

Together, they replace what release managers and release trains used to do manually: catch bad code before it ships, control exposure separately from deployment, know whether trunk can safely reach production, and know exactly where a hotfix belongs.

That is the trade this series is really about. Less branch ceremony. More operational honesty. Faster feedback. Fewer release superstitions.

There's a fifth piece coming eventually — testing an OTA update against the real production binary before any real user sees it, without a second build. That's a post of its own once it's actually shipped.

Why We Ditched Git-Flow for Trunk-Based Mobile Releases

Soham Mondal — Tue, 25 Aug 2026 17:49:59 +0000

If you've shipped a React Native app on git-flow, you know the tax. develop, release/x.y.z, a hotfix branch nobody merges back cleanly, a changelog somebody writes half-awake before store submission, and a release manager doing branch archaeology to answer a simple question: "what is actually in production right now?"

Git-flow did not break for us because branching theory is flawed. It broke because mobile release safety was being enforced by memory, rituals, and good intentions. That is manageable right up until you're moving fast, juggling OTA updates, store binaries, native dependencies, and the very real fact that Apple does not care that your branches looked tidy.

We moved our React Native app to trunk-based development. Everything lands on main. No long-lived develop. No babysitting release/* branches. No merge-back ceremony after a hotfix. But the important part is not "fewer branches." The important part is that the decision of whether a commit becomes an OTA update or a full store release is not made by a human anymore. Our release orchestrator makes that call after checking the app's native fingerprint.

That, to me, is what a mature Expo/React Native release setup looks like: one trunk, boring release mechanics, and explicit guardrails around the native/runtime boundary.

Git-flow vs trunk-based, in one line
Git-flow tries to create safety with branch structure. Trunk-based development tries to create safety with fast integration and stronger automation.

OTA update
In Expo/EAS Update terms, OTA means shipping JavaScript and assets to already-installed binaries without waiting for App Store review. It cannot change native code, native dependencies, permissions, or anything else baked into the binary. Expo's docs are clear on that boundary.

This shift was partly opinionated and partly practical. I had asked peers in the Expo community what they were doing for branching strategy, and the answers were all over the place: some still used release branches, some shipped almost everything from main, some had custom hybrids built around EAS Update and hotfix pressure. That thread reinforced something I already suspected: there isn't one blessed branch model for React Native. But there is a pattern. Teams that get good at shipping keep removing manual release decisions.

For context, that discussion is here: What's your team's branching strategy for React Native / Expo?

The one idea that makes this work

Mobile has a problem web does not: most of your code can update instantly over the air, but some of it is physically baked into a binary already sitting in the App Store or Play Store. Once that binary is installed, there is no clever branching strategy that lets you OTA your way around a native mismatch.

So the whole system rests on one question, asked by a machine, not by a human in a release Slack channel:

Does this code produce the same native fingerprint as what's already in the store?

Every native-relevant input gets hashed into a fingerprint: native dependencies, config plugins, platform config, and other inputs that affect the runtime baked into the app. Expo has been pushing this model pretty hard, and rightly so. If you use runtimeVersion with the fingerprint policy, that compatibility boundary is no longer a hand-maintained version string. It is derived from the actual native shape of the app.

That means the release system does not need somebody to eyeball a PR and say, "eh, this seems JS-only." It can compute the answer.

Native fingerprint
Expo Fingerprint is effectively a hash of the app's native-relevant surface area. If that hash changes, the binary and update may no longer be compatible. See the Expo Fingerprint docs and runtime version docs.

$ eas fingerprint:compare --build <latest-production-build-id>
✔ Fingerprints match
No native changes detected for this runtime.

$ eas fingerprint:compare --build <latest-production-build-id>
✖ Fingerprints do not match
Changed sources:
  + app.config.ts
  + ios/Podfile.lock
  + android/gradle/libs.versions.toml

This update needs a new binary before it can ship safely.

That diff is the useful bit. Not just "hash mismatch, good luck," but the actual sources that changed. That is the difference between a five-minute investigation and an hour of people arguing whether a dependency bump really changed the runtime.

A few examples of changes that look innocent until they aren't:

Adding a package that includes a native module.
Changing an Expo config plugin.
Bumping an SDK that rewrites native build files.
Touching permissions, entitlements, or platform-specific build config.

In git-flow, somebody has to remember those rules. In a mature Expo pipeline, the orchestrator enforces them.

OTA vs. full release, decided by the orchestrator

A release request should not ask a human to choose between ota and full-release. That's exactly the decision humans get wrong under pressure.

The better model is simple: trigger one release workflow, let it inspect the current state, then route to the correct path.

on:
  workflow_dispatch:
jobs:
  decide-release-mode:
    runs-on: ubuntu-latest
    outputs:
      mode: ${{ steps.decide.outputs.mode }}
    steps:
      - uses: actions/checkout@v4
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci

      - id: decide
        run: |
          if eas fingerprint:compare --build "$LATEST_PROD_BUILD_ID" --non-interactive; then
            echo "mode=ota" >> "$GITHUB_OUTPUT"
          else
            echo "mode=full-release" >> "$GITHUB_OUTPUT"
          fi

  ota:
    needs: decide-release-mode
    if: ${{ needs.decide-release-mode.outputs.mode == 'ota' }}
    runs-on: ubuntu-latest
    steps:
      - run: eas update --branch production --message "$(git log -1 --pretty=%s)"

  full-release:
    needs: decide-release-mode
    if: ${{ needs.decide-release-mode.outputs.mode == 'full-release' }}
    runs-on: ubuntu-latest
    steps:
      - run: eas build --platform all --profile production --non-interactive
      - run: eas submit --platform all --latest --non-interactive

That is not meant to be copy-paste production YAML. It is the architectural point: one release intent goes in, the workflow decides the path.

If the fingerprint matches the latest production binary, ship OTA in minutes. If it doesn't, cut a real binary and submit it. Same trigger, different outcome, machine-decided.

This is also easier to explain to the team. Engineers do not need a release-mode flowchart in their heads. They need one rule: merge to main, and let the orchestrator classify the change.

That approach lines up with where Expo/EAS has been heading. EAS Update, EAS Build, runtime versioning, and fingerprint-aware compatibility are all steering toward the same idea: stop treating release safety as tribal knowledge. Encode it.

What actually happens on a release

The best release systems are boring in the right places. Nobody should be hand-editing version numbers or typing release notes into a markdown file five minutes before submit.

When a release is triggered, the pipeline should do roughly this:

Cut a release PR that bumps the app version and generates a changelog from commit history.
Merge that PR, tag the commit, and build/submit from that exact revision.
Pin a snapshot branch at the shipped commit so "what is in production" is a Git ref, not a memory exercise.

That store/1.24.0+512 branch is not a long-lived release branch. It is a frozen pointer to the exact commit that became the store binary.

That distinction matters.

In git-flow, release/* branches tend to become semi-alive places where extra fixes, cherry-picks, and "just this one last thing" changes accumulate. In a trunk-based mobile setup, the snapshot branch should stay dumb. It exists so that when production breaks, you know exactly where to branch the hotfix from.

Snapshot branch
A snapshot branch is just a named Git ref pinned to the exact shipped commit. It is not a second lane of active development. Its job is traceability and safe hotfix routing.

That means a hotfix flow becomes much less ambiguous:

If the bug affects the live store binary, branch from the latest store snapshot.
If it's OTA-compatible, the orchestrator can publish it quickly once merged.
If it changes the native fingerprint, the orchestrator forces the full-release path.
Either way, main remains the source of truth, not a maze of partially-synced branches.

flowchart LR
    A1(( )) --> A2(( )) --> A3([Release commit]) --> A4(( )) --> A5(( ))
    A3 --> S[store/1.24.0+512 snapshot]
    S --> H{Hotfix needed?}
    H -->|Yes| P[Patch from snapshot]
    P --> M[Merge forward into main]

    classDef commit fill:#fffaf2,stroke:#171717,color:#171717,stroke-width:2px;
    classDef release fill:#f4e1bd,stroke:#171717,color:#171717,stroke-width:2px;
    classDef snapshot fill:#efe6d8,stroke:#171717,color:#171717,stroke-width:2px;
    classDef action fill:#f7f1e8,stroke:#171717,color:#171717,stroke-width:2px;
    classDef accent fill:#f0b35f,stroke:#171717,color:#171717,stroke-width:2px;

    class A1,A2,A4,A5 commit;
    class A3 release;
    class S snapshot;
    class H action;
    class P,M accent;

This is the part people often miss when they hear "trunk-based for mobile." They imagine recklessness. In practice, a mature setup is more constrained than git-flow. Fewer branches, yes. More automation, definitely. But also stricter compatibility checks, clearer release provenance, and much less room for subjective judgment calls.

If you're building on Expo today, it's worth reading the official EAS Update docs and watching the work the Expo team is doing around runtime versions, updates, and workflows. The release maturity story is getting better because the underlying primitives are getting better.

The Expo blog has had a few solid posts in this area too. David Davidov's write-up on Posh's move toward continuous delivery is worth a read, and Jacob Clausen's post on app variants is adjacent in a useful way once you start thinking seriously about release lanes, environments, and binary identity.

Also, credit where it's due: people building in the Expo/EAS space have made this conversation more concrete over the last couple of years. The tooling is better, the operational model is clearer, and mobile teams finally have a credible path away from branch-heavy release rituals.

Part 2 is where the rest of the safety story picks up: test gates, feature-flag discipline, and hotfix routing without turning main into a panic lane.

How to setup 2 separate Git profiles on a single device?

Soham Mondal — Thu, 09 Apr 2020 16:27:26 +0000

I work on a single device and use it for both my office work and side/pet/personal projects. Default git credentials for the device is obviously the one provided by my office. Now, this scenario has happened to me a lot of times -

My office work is done
I am super excited about a personal project idea
So I set up a remote git repository
Set up the project boilerplate locally
Fire git init, git remote add, git add, git commit & PUSH!!!

And it is then when I realize I have pushed code to my personal git with wrong (office) credentials. And I start all over again.

Do let me know if you have ever faced a similar situation like mine in comments!

So, now what is the solution? How do I have separate git config on a single machine? The answer is pretty simple. You need to have two separate Git config files. But, how ? Read on...

*** Before starting make sure you have git version 2.13 or higher installed in your system. ***

$ git --version
git version 2.14.2

Now with the prerequisites set, let's begin -

Your .gitconfig resides in your home directory. For Windows users, it will be in the path C:\Users\[YOUR_NAME]. Go to that directory.
Create two separate folders like My_Office_Workspace & My_Personal_Workspace.
Create two separate .gitconfig files, one for office and another for personal usage in the path C:\Users\[YOUR_NAME]. Let's name them .gitconfig-office & .gitconfig-personal.

The contents of .gitconfig-office -

# This is Git's per-user configuration file.
[user]
name = YOUR_OFFICE_GIT_USERNAME
email = your.name@company.com

The contents of .gitconfig-personal -

# This is Git's per-user configuration file.
[user]
name = YOUR_PERSONAL_GIT_USERNAME
email = your.name@gmail.com

After that's done, open up the .gitconfig file, and make the necessary changes. It should look like -

[includeIf "gitdir:~/My_Office_Workspace/"]
  path = .gitconfig-office
[includeIf "gitdir:~/My_Personal_Workspace/"]
  path = .gitconfig-personal

Configuration done! Now let's verify.

Goto My_Office_Workspace and clone a project from your office GitHub, BitBucket or GitLab. Let's call the project My_Office_Project and do the following -

$ cd My_Office_Workspace/
$ git clone https://github.my_office.com/VeryImportant/My_Office_Project.git
$ cd My_Office_Project/
$ git config user.name
YOUR_OFFICE_GIT_USERNAME

You can also do the same for your personal projects under My_Perosonal_Workspace, but you will see you the output for the last command git config user.name is YOUR_PERSONAL_GIT_USERNAME.

Woohoo, it's done! No more messing up. 😃

Update

If your projects are in a different drive on Windows, for eg. D or F, then you can configure the .gitconfig like this

[includeIf "gitdir:D:/My_Office_Workspace/"]
  path = .gitconfig-office
[includeIf "gitdir:F:/My_Personal_Workspace/"]
  path = .gitconfig-personal

Liked this post? Share it ↩️ or maybe give a heart 🧡.

I am Soham Mondal, a developer from India. You can follow me on LinkedIn, Instagram, or GitHub. You can learn more about me on my website. I am currently open to new projects & job offers.