Forem: Amanda Gama

A Live Activity isn't a notification

Amanda Gama — Tue, 05 May 2026 01:59:54 +0000

You're in another app and there's a timer counting down at the top of your phone. You lock the screen and the same timer is sitting there. You swipe down to the Notification Center and it's there too, still ticking. It looks like a notification, but a notification can't tick.

That's a Live Activity. It looks like three different surfaces (Dynamic Island, lock-screen banner, Notification Center entry), but they're the same widget, rendered three ways by the OS. I wired one up for Tomoe, a focus timer I built. The punch line: it took a weekend. Most of that weekend was unlearning what I thought a Live Activity was. Once the shape clicked, the code was small.

This post is the shape.

What a Live Activity actually is

Three things that get glossed over in most tutorials:

It's a widget, not a notification. The view code lives in a Widget Extension target, separate from your app. The app pushes state; the extension renders pixels. If you've shipped a Home Screen widget before, this is the same story.

It's driven by a typed ContentState. You declare a Codable struct of "things that change" and call .update() with a new instance. There's no general "set arbitrary text" API. The schema is the contract.

The OS renders the timer. If you reach for Timer or a 1-second TimelineView, you're already off the path. SwiftUI's Text(timerInterval:countsDown:) lets the OS rasterise the countdown for you. Your widget doesn't wake every second. It can't; the budget would never allow it.

Two pieces of plumbing before any of this works. Declare NSSupportsLiveActivities in the app's Info.plist:

<key>NSSupportsLiveActivities</key>
<true/>

…and target iOS 16.2 or later. The 16.0 / 16.1 ActivityKit surface churned, and the workarounds aren't worth it.

The data model

Every Live Activity is keyed by an ActivityAttributes type. You split it into "stuff that's fixed for the life of the activity" (the attributes themselves) and "stuff that changes" (the nested ContentState).

Tomoe's looks like this:

public struct TomoeActivityAttributes: ActivityAttributes {
    public struct ContentState: Codable, Hashable {
        public var endDate: Date
        public var isPaused: Bool
        public var pausedRemainingSeconds: Int
    }

    public var task: String
}

The task name doesn't change once a session starts, so it's an attribute. The end timestamp, pause flag, and the snapshot for rendering paused state all change, so they're in ContentState. Codable + Hashable is how the OS serialises state across the app/widget process boundary.

The detail that costs everyone an afternoon: this file has to be a member of both targets, the app target and the widget extension target. Xcode won't warn you. The activity will start, and then the widget will silently fail to decode the state and render nothing. Check the file inspector before you debug anything else.

The four Dynamic Island slots

Here's where the mental model clicks. The DynamicIsland { … } builder gives you four slots, each for a different state of the same activity:

compactLeading and compactTrailing: the two tiny views you see hugging the camera cutout when only your activity is active.
minimal: what you're demoted to when another app also has an active Live Activity. You're now a circle next to a dot.
expanded: what the user sees when they long-press.

Plus the lock-screen / Notification Center view, which is the top-level body of the ActivityConfiguration. The same view code renders in both places. The OS just changes the chrome around it.

Trimmed to the load-bearing parts, Tomoe's whole widget is:

struct TomoeWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: TomoeActivityAttributes.self) { context in
            LockScreenView(context: context)
                .activityBackgroundTint(cream)
                .activitySystemActionForegroundColor(ink)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) { /* mark + task name */ }
                DynamicIslandExpandedRegion(.trailing) {
                    TimerView(state: context.state, fontSize: 38, color: .white)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    if context.state.isPaused { Text("paused") }
                }
            } compactLeading: {
                TomoeMark(size: 22)
            } compactTrailing: {
                TimerView(state: context.state, fontSize: 22, color: .white)
            } minimal: {
                TomoeMark(size: 20)
            }
            .keylineTint(accent)
        }
    }
}

Two things to keep in mind.

The compact regions are tiny. Tomoe's brand mark is 22pt; the trailing timer is 22pt at a minimum width of 56pt. Anything bigger overflows. Design for ~40pt of width and treat anything more as a bonus.

The minimal view appears without warning, the moment any other app starts an activity. Don't put information in compactLeading that needs to also be in minimal. Those are different layers, and you don't get a transition between them.

Let the OS tick

The single most useful API in this whole stack:

Text(timerInterval: Date()...state.endDate, countsDown: true)
    .monospacedDigit()

You give it a date range; you get back a Text that the OS counts down for you. It updates without your widget doing anything. This is what makes the timer feel native: no flicker, no off-by-one, no battery cost.

The catch: you can't pause it. The OS counts to the end of the range, period. So when the user pauses, Tomoe swaps to a static label:

if state.isPaused {
    Text(pausedTimeString(seconds: state.pausedRemainingSeconds))
} else {
    Text(timerInterval: Date()...state.endDate, countsDown: true)
}

On pause, I push an update with isPaused: true and a snapshot of the remaining seconds. The widget renders that snapshot until the next state change. On resume, I push a new endDate = now + remaining and we're back on the OS-driven interval.

pausedRemainingSeconds is the non-obvious part: I have to send the value the widget should display, because the widget process has no idea how long ago I paused.

Pushing updates from the app

The lifecycle is three calls. From Tomoe's bridge module, trimmed:

let activity = try Activity.request(
    attributes: attributes,
    content: .init(state: state, staleDate: nil),
    pushType: nil
)

// later, on pause/resume
await activity.update(.init(state: newState, staleDate: nil))

// done
await activity.end(nil, dismissalPolicy: .immediate)

pushType: nil means "I'll push state from this app process." That's right for a timer. The app already knows when the user paused or finished. The other option is .token, which lets you push from a server via APNs. Useful for Uber-style "your driver is here" updates that the app itself can't observe; overkill for anything the foreground app can drive.

The budget you should know about, so you don't design something that fights it:

An activity can live for about 8 hours before the OS forces it stale.
ContentState is capped at ~4 KB encoded.
Updates are rate-limited; push every 100ms and the OS quietly drops most of them.
A stale activity dims on the lock screen but doesn't disappear until you call .end() or the user dismisses it.

That last one matters more than it sounds: passing an endDate in the past does not auto-end the activity. The countdown will show 00:00 and just sit there. You have to call .end() yourself when the timer reaches zero. In Tomoe I do this from the JS layer when the timer fires, since the app is React Native. But the Swift Activity.request / .update / .end API is the same regardless of host. Flutter, RN, native, doesn't matter; the shape is identical.

Things that bit me

Shared types break easily. The ActivityAttributes file has to belong to both targets. Add → File Inspector → check both Target Memberships. If your activity starts but the widget renders empty, this is it. Every time.

Dynamic Island regions ignore overflow. SwiftUI happily lets you put a wide view in compactTrailing. The OS will clip it without a warning at build time. Use .minimumScaleFactor(0.6) and .lineLimit(1) defensively, especially on numeric content where the digit count varies.

Asset catalogs are flaky in widget extensions. I had a brand image that loaded fine in the simulator and failed silently on device. I switched to a SwiftUI-drawn mark (a coloured rectangle with an SF Symbol on top) and the problem went away. If a widget asset isn't appearing on a real iPhone, that's the first thing to try.

Closing

What surprised me about Live Activities is how little there is to them once you've named the parts. A typed ContentState, four Dynamic Island slots, one OS-driven timer view, three lifecycle calls. That's the whole API surface for a focus timer. Most of the hard work happens before you write code: deciding what to put in the compact view, what's worth a long-press to expand, what the paused state should feel like.

I built Tomoe to scratch my own itch for a focus timer that doesn't shout. Three calm scenes: rain, stars, fireflies. Four session lengths. No accounts, no tracking, no streaks to break. The timer follows you out of the app, into the Dynamic Island and onto the lock screen, exactly the way this post describes. Available on the App Store.

Becoming a tech lead, what I wish someone had told me

Amanda Gama — Mon, 04 May 2026 13:07:30 +0000

Becoming a tech lead was the goal from pretty early in my career. I had a clear picture of what the role was. More responsibility, more influence over the work, more of the interesting problems landing on my desk because someone had to figure them out and that someone, finally, would be me. It read like the natural next step. The thing you graduate to once you're good enough.

What that picture didn't include was the part of the job that's about leading people. Not management. I knew management was a separate track. I mean the quieter stuff. Sitting with someone else's frustration and not fixing it for them. Holding a position you're 60% sure of in a room of people who want a confident answer. Realizing the thing blocking the team isn't a technical problem, and that nothing in your background really prepared you for the actual one.

This is the post I wish someone had written for me when I was still aiming for the role. Not the ladder advice. The hard parts.

What changed in the day

The honest version of the shift isn't what you read in leadership posts. Yes, there are more meetings. Everyone says that. The meeting count is the easy part to see and the easy part to adapt to. The ones I took longer to notice were quieter.

The first one is your relationship to shipping. As an engineer, the day has a clean ledger. You opened a PR, you closed an issue, you merged a branch. Even on a slow day there's a diff that proves you were here. As a tech lead, half of your most important work doesn't show up that way. You sat in a meeting and changed the direction of a project. You unblocked someone in a thirty-minute conversation. You wrote a short doc that prevented two weeks of wasted work next month. None of that has a green checkmark next to it. The first few months I felt vaguely guilty at the end of every day, because I couldn't point to a thing I'd built. The fix wasn't to build more. It was to stop measuring my day in commits.

The second is the time horizon. Engineering work runs in days. A bug, a feature, a refactor: a thing you can hold in your head start to finish. The lead work runs in weeks and quarters. A hire decision today shapes the team six months out. A standard you set now shows up in code reviews a year from now. The horizon stretches and the feedback loops stretch with it. You stop knowing whether a call you made was a good one for a long time, and sometimes you never really know.

The third is that the day stops having a clean end. When you closed the laptop as an engineer, you were done. The remaining work was on a list, sitting still. As a lead, the open threads keep moving while you sleep. Someone hit something hard at 11pm. A project is drifting and you can feel it without anyone saying so. There's always a thing you could think about more. The skill is learning to put it down anyway.

The fourth is a new kind of fatigue. Coding is mentally taxing in a contained way. You're tired, you go for a walk, you come back. The fatigue from a day of decisions and context switches is different. It doesn't lift the same way. It's lower-grade and longer-tailed. Nobody warned me about it, and I spent the better part of a year thinking I was just under-sleeping.

What advice I stopped giving

There's a list of things I used to say to junior engineers with full conviction. Most of them I'd picked up from people I respected, and some I'd defended in arguments. Sitting in the lead chair quietly took a few of them apart.

I stopped telling people to always push back on bad requirements. The advice isn't wrong, exactly. It's too neat. The version I gave didn't account for what bad requirements actually look like in the wild: usually a partial picture from someone who's already negotiated three other constraints you can't see. The right move is rarely "push back." It's "ask what changes if X." Most of the time the requirement isn't bad. You just don't know what it's load-bearing for yet.

I stopped saying ship fast as a default. Speed matters. The trouble is that ship-fast gets treated as a virtue independent of context, which is how teams end up shipping things that take a year to undo. Some decisions deserve to be slow. Anything that's expensive to reverse (a data model, a hire, a public commitment, a foundational dependency) deserves the time. Speed on the reversible stuff, slowness on the rest. I should have been more careful about which one I was preaching.

I stopped telling people to always speak up in meetings. The advice was pitched at people who under-contribute, which is a real failure mode. But there's an opposite one I didn't account for: the person who fills every silence and pushes the team into worse decisions because nobody slowed them down. Sometimes the best thing you can do in a room is wait. Let the question sit. See what someone else says.

I stopped saying the right tech wins. It doesn't. Alignment wins. The team that picked the okay-but-aligned tool will out-ship the team that picked the better-but-contested one almost every time. The energy you spend defending a technical choice is energy you don't spend using it. I'd watched this happen to other teams and thought we were the exception. We weren't.

The pattern under all of those: the advice I used to give was advice for the version of the job I'd imagined. Sitting in the chair changed which trade-offs I could see.

The rituals that survived

Most of what I did to stay organized as an engineer didn't survive the role change. Tickets I lived in stopped being where my work happened. The PR queue stopped being a useful daily anchor. The deep-work blocks I'd guarded for years got eaten by a calendar I no longer fully controlled. I had to rebuild a lot of it.

What survived is small. Two habits, one rule.

The first habit is a written end-of-day. Five lines, plain text, takes three minutes. What I decided today. What I'm still unsure about. Who's blocked on me. Who I'm blocked on. One thing I want to start with tomorrow. I tried more elaborate systems and they all collapsed within a month. The five-line version has stuck because it's small enough that I actually do it on bad days, which are the days you most need it.

The second habit is reading code I didn't write, on purpose, every week. Not to review it. Just to read it. As a lead it's easy to drift away from the codebase, and a few weeks of that is enough that your suggestions in design reviews start feeling slightly off to the people doing the work. An hour a week of just reading what the team is shipping keeps the drift smaller. It doesn't make me an expert in everything. It makes me less wrong.

The rule is: don't bring up pattern-y problems without sitting with them for 24 hours first. Not the urgent ones. Those go straight up. I mean the "something feels off about how we're approaching X" ones. If I raise that in the moment, half the time I'm reacting to one bad meeting, not a real problem. If it still feels true the next day, it's worth bringing up, and I bring it up better. The 24-hour rule has saved me from a lot of needless team-level drama, almost all of it self-inflicted.

What I assumed would stick and didn't: the deep-work blocks. I tried to defend them and lost. Most days now my best heads-down hour is the one between waking up and the team coming online, not a block I scheduled. Recreating engineer rhythms in a lead's calendar was a year of frustration before I gave up.

Also gone: my old habit of replying to messages in batches. As an engineer it was a productivity move. As a lead, leaving four people waiting six hours each is its own kind of cost.

What I'd tell my earlier self

A short list of things I'd say to the version of me who was aiming for this role.

The job is mostly about people, even the technical parts. The technical parts that are still purely technical mostly aren't yours to do anymore. Make peace with that earlier than I did.

You don't need to have the answer. You need to make sure the team gets to one. Those are different jobs and they require different muscles. The first one is the one you spent a decade training. The second one is mostly new.

Confidence will be asked of you in moments when you don't have it. Faking it doesn't work, because people can tell. Saying "I'm not sure, here's how we'll find out" works almost every time, and the people you respect most are the ones who already do this.

Most of the advice you give right now is for the role you have, not the one you're aiming at. That's not a problem. Just know that some of it will quietly stop being true.

The role isn't a promotion in the way you imagine. It's a different job. You'll be a beginner again at parts of it, and the bits where you're a beginner will turn out to be the most important bits.

The hard parts are the job. Not a side effect of it. Not something to optimize away. If you want the role, the part you're nervous about is most of what you'd be doing.

Push notifications, the iceberg under one feature

Amanda Gama — Mon, 04 May 2026 02:29:09 +0000

It's a one-line item on the roadmap. "Send a push notification when X happens." Estimate is two days, three if the backend doesn't have FCM credentials yet. There's a library for it.

The library is the visible part. The other 90% is platform lifecycle, registration state machines, race conditions with navigation, payload archaeology, and a half-dozen iOS and Android quirks. Nobody writes them down. You learn them after you ship, when the bug reports start coming in.

I built this stack with custom native modules, wrapping APNs on iOS and FCM on Android directly, instead of reaching for Notifee, React Native Firebase, or OneSignal. The trade was the obvious one. I gave up the abstraction the libraries provide and got control over every edge case in return. The decision wasn't ideological. The failure modes I cared about were already filed against those libraries, unfixed.

This post is what's underneath. Not the library you import. The work the library is hiding from you, or trying to.

The waterline: registration is a state machine, not a function call

The tutorial version is one line:

const token = await messaging().getToken()
sendToBackend(token)

What's actually happening is a few rounds of back-and-forth between the OS, your app, and the push provider. At least three places it can quietly stop working.

On iOS, registration is split across delegate methods. The token comes back as NSData, not a string, and you hex-encode it before anyone outside the AppDelegate gets to see it:

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  const unsigned char *bytes = deviceToken.bytes;
  NSMutableString *hex = [NSMutableString stringWithCapacity:(deviceToken.length * 2)];
  for (NSUInteger i = 0; i < deviceToken.length; ++i) {
    [hex appendFormat:@"%02x", bytes[i]];
  }
  [[NSNotificationCenter defaultCenter]
      postNotificationName:@"DeviceTokenRegistered"
                    object:nil
                  userInfo:@{ @"token": hex }];
}

That's the documented part. Three things aren't.

iOS 18+ silently drops the first registration call if you make it immediately after the user grants permission. No error, no callback, nothing. A 1.5 to 2 second delay and one retry recovers from it almost every time:

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(2.0 * NSEC_PER_SEC)),
               dispatch_get_main_queue(), ^{
  if (![UIApplication.sharedApplication isRegisteredForRemoteNotifications]) {
    [UIApplication.sharedApplication registerForRemoteNotifications];
  }
});

This isn't in any Apple doc. I found it after enough TestFlight users on iOS 18 reported notifications "just not working."

Tokens change. APNs rotates them on app reinstall, restore-from-backup, or migration to a new device. FCM rotates on its own schedule. If you don't dedupe registrations, you re-register the same device on every cold start and your backend's device tables grow forever.

Token callbacks outlive their context. A token refresh that fired pre-logout can land post-logout, and re-bind the device to the previous user. The cheap fix: hold a lastRegisteredToken ref and short-circuit any callback whose token matches what you just sent.

That's three places one line of pseudocode is hiding.

Permissions are three different things

iOS, Android pre-13, Android 13+. Each one is a different model, and you handle all three in one codebase.

iOS is the cleanest. Request Alert | Sound | Badge once, the OS gives you a yes/no. There are extras most apps never use: provisional authorization (notifications go straight to the notification center), critical alerts (bypass Do Not Disturb), time-sensitive alerts on iOS 15+. The core flow is one async call. Catch: if the user denies, you can never re-prompt. They go to Settings or nothing.

Android pre-13 has no runtime permission for notifications at all. As long as the user installed your app, you can post. But on Android 8+ you have to create a notification channel first or the notification is silently dropped. The channel is also where importance, sound, and vibration live, not the notification itself:

fun ensureChannel(context: Context) {
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    val channel = NotificationChannel(
      CHANNEL_ID,
      "General",
      NotificationManager.IMPORTANCE_HIGH
    ).apply {
      description = "App notifications"
      enableVibration(true)
    }
    val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
    manager.createNotificationChannel(channel)
  }
}

IMPORTANCE_HIGH is what enables heads-up banners. IMPORTANCE_DEFAULT puts the notification in the tray with no popup. The user can override your importance from settings, and you have no recourse.

Android 13+ added POST_NOTIFICATIONS as a runtime permission. You declare it in the manifest, request it at runtime, and check the SDK level before requesting because the API doesn't exist below 33. Like iOS, a denied permission has to be re-granted from system settings.

The branch you actually write:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
  if (ContextCompat.checkSelfPermission(context, POST_NOTIFICATIONS) != GRANTED) {
    ActivityCompat.requestPermissions(activity, arrayOf(POST_NOTIFICATIONS), 1)
  }
}
ensureChannel(context)

Three platforms, three permission models, one codebase. None of this is in the tutorial.

Three app states, three completely different code paths

This is the centerpiece of the iceberg. The same notification has to be handled three ways, depending on what the app is doing when it arrives.

State	iOS callback	Android callback	OS shows banner?	App can react before tap?
Foreground	`willPresentNotification:`	`onMessageReceived` (FCM service)	No (you choose)	Yes
Background	`didReceiveNotificationResponse:` (on tap)	`onMessageReceived` + tap intent	Yes	No
Quit / killed	`launchOptions[...RemoteNotificationKey]`	Intent extra in `MainActivity`	Yes	No

Each row hides something.

Foreground. iOS does not show a system banner when the app is open. You decide. The decision is one option mask returned from willPresentNotification::

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))handler {
  NSDictionary *aps = notification.request.content.userInfo[@"aps"];
  BOOL silent = [aps[@"content-available"] intValue] == 1 && !aps[@"alert"];
  handler(silent
    ? UNNotificationPresentationOptionNone
    : UNNotificationPresentationOptionAlert
        | UNNotificationPresentationOptionSound
        | UNNotificationPresentationOptionBadge);
}

Skip this delegate method and foreground notifications vanish. You'll spend a week wondering why testing-on-device fails to reproduce what users are seeing.

Android has no equivalent. The FCM service runs on every notification regardless of state, so you detect foreground yourself:

val info = ActivityManager.RunningAppProcessInfo()
ActivityManager.getMyMemoryState(info)
val isForeground = info.importance == IMPORTANCE_FOREGROUND

Foreground: suppress the system notification, let JS render its own banner. Background: build the system notification and post it.

Background. The OS shows the banner. Your code runs only when the user taps. iOS hands you the payload via didReceiveNotificationResponse:. Android hands you the intent in MainActivity.onCreate or onNewIntent.

Quit. The app process is dead. The OS shows the banner. On tap, the app cold-starts, and your notification handler doesn't exist yet. JavaScript hasn't been loaded. The payload is delivered as a launch option (iOS) or an intent extra (Android), and you have to retrieve it after React mounts:

const initial = await Notifications.getInitialNotification()
if (initial) {
  setRedirectTarget(parseNotification(initial, { bootingApp: true }))
}

On Android, the cleanest move is to write the payload to SharedPreferences in the FCM service when the app isn't running, then read it back when JS comes online. Skip this and the launch intent gets consumed by the OS before your code is alive to see it.

The mistake I made first was writing one handler. They look like the same event from JS. They are not. The cold-start payload on iOS is shaped differently from the foreground one. The Android intent doesn't look like the FCM message your foreground handler receives. We'll get to that.

The race nobody warns you about

A user taps a notification. The app was killed. The OS hands you the payload before:

React has mounted
Your navigation container is ready
Auth state has hydrated from storage
The initial data fetch has resolved

Call navigation.navigate(...) here and three things can happen, all bad. You crash. You no-op silently and the user is stuck on the splash screen. Or you navigate, but auth is empty. The screen renders unauthenticated and bounces them to login. Confusing, since they came in through a notification that implied they were already signed in.

The fix is a "deferred redirect" pattern. Notifications never navigate directly. They write a target into context state. A separate effect watches both the target and a readyToRedirect flag, and only fires when every precondition holds:

const readyToRedirect = useMemo(
  () => isLoggedIn
     && !isFirstLogin
     && hasSeenOnboarding
     && !isHydrating,
  [isLoggedIn, isFirstLogin, hasSeenOnboarding, isHydrating]
)

useEffect(() => {
  if (readyToRedirect && redirectTarget) {
    navigationRef.current?.dispatch(
      CommonActions.reset({
        index: 1,
        routes: [{ name: 'Home' }, { name: 'Detail', params: redirectTarget }],
      })
    )
    setRedirectTarget(null)
  }
}, [readyToRedirect, redirectTarget])

The same pattern handles a more annoying case: the user is in the foreground, a notification comes in, they tap the in-app banner, but their session expired between the banner appearing and the tap. The redirect waits in state until auth re-hydrates, then fires. The tap doesn't get lost.

The corollary is about when you register listeners. Don't register on app startup. Register only when appStateVisible === 'active' && isLoggedIn. Otherwise the very first launch (fresh install, logged out, no auth state) fires a redirect to a screen the user can't open, and the navigator throws.

A "wait until ready" gate sounds trivial until you count how many things have to be ready. In production I count four: auth, navigation, hydrated storage, first paint. Miss any one and the bug only reproduces on cold starts triggered by notifications. Every notification.

The payload is not the payload

A notification on iOS arrives in three or four shapes depending on app state.

Foreground: top-level title, body, custom data on customData
Cold start (from launchOptions): aps.alert.title, aps.alert.body, custom data still on customData
Silent push: aps.content-available: 1, no alert, custom data only

Android adds another twist. FCM only allows string-string maps in the data field, so any structured custom data is JSON-stringified by the sender. You parse it on the JS side, in a try/catch, with a logged warning on failure. Skip the try/catch and a single malformed payload from the backend silently breaks your entire notification handler.

The only sane move is a normalizer. One parseNotification that returns a single shape, and the rest of the app only ever sees that shape:

type ParsedNotification = {
  type: 'redirect' | 'silent' | 'broadcast'
  title: string
  body: string
  targetId?: string
  url?: string
}

function parseNotification(raw: RawNotification, opts: ParseOpts): ParsedNotification {
  if (opts.platform === 'android') {
    const data = safeJSON(raw.customData) ?? {}
    return { type: data.type ?? 'broadcast', title: raw.title,
             body: raw.body, targetId: data.id, url: data.url }
  }
  if (opts.bootingApp) {
    return { type: raw.aps.customData?.type ?? 'broadcast',
             title: raw.aps.alert?.title ?? '',
             body: raw.aps.alert?.body ?? '',
             targetId: raw.aps.customData?.id }
  }
  return { type: raw.aps.customData?.type ?? 'broadcast',
           title: raw.title, body: raw.body,
           targetId: raw.aps.customData?.id }
}

Tests cover each variant: cold-start iOS, foreground iOS, Android with valid JSON, Android with malformed JSON. The malformed-JSON test is the one that catches the bug. Every time the backend ships a payload change without telling mobile, the test fails before it ships.

The bits you'll only learn by shipping

Things that aren't in any tutorial. I learned each of these from a bug report.

Notification Service Extensions have a 30-second budget. If you're modifying notifications in a Service Extension (decryption, downloading rich media, sending delivery receipts), the OS kills the extension and delivers the original payload if you overshoot. Set a 5-second timeout on any HTTP work the extension does. The user gets the notification either way, but you don't want a silently-truncated payload because the network was slow.

App icon badges are yours to manage. The OS doesn't decrement them when the user reads a notification. You set the count from the app, from the server, or both, and reset to zero when the relevant view mounts.

Delivery receipts are a fourth code path. If you want to know which notifications were actually delivered, you wire receipts in three places: the Service Extension fires "received" before the user sees the banner, the foreground/tap handler fires "read on tap," and silent push fires "received" again. None of these deduplicate. The backend has to.

Token refresh fires while you're logged out. FCM rotates on its own schedule. If your registration code doesn't check whether anyone's logged in, you'll re-bind the device to a stale or wrong user. Guard with a stored lastRegisteredFor and a "user is currently logged in" check.

Direct boot. If you want notifications to surface while the device is encrypted-and-locked (post-reboot, pre-unlock), your FCM service needs directBootAware="true" in the manifest, and you can only access protected storage. Most apps don't need this. The ones that do really need it.

Foreground listener leaks. Register on resume, unregister on background. Otherwise context updates fire after the relevant component unmounts, and you log a setState on unmounted component warning every time a notification arrives. The user sees nothing wrong. Your error logs fill up.

None of these are in the README. They become the README, after.

What I got back

What I have now is a push notification system that survives every state combination I've actually seen: cold start, mid-login, kill-and-relaunch, OS reboot, denied-then-granted permissions, foreground notification while a session is timing out. The path the user actually takes is rarely the one in the demo video.

A few concrete things came out of it:

A parseNotification normalizer with tests covering four payload shapes, runnable in plain Node, no native bridges required
A clean seam: native owns registration, foreground display, OS plumbing, intent retrieval. JS owns parsing, navigation, product logic. They don't drift because they speak through one event shape.
A deferred-redirect pattern that handles cold-start, foreground, and re-auth races with one piece of code

And the cost. Every iOS major version, every Android API bump, I have to revisit this. The libraries would have absorbed some of it. I chose not to use them because the failure modes I cared about (iOS 18 registration, cold-start payload divergence, silent push receipts, the navigation race) were already filed against those libraries, unfixed. That's the trade I made. I'd make it again, knowing the maintenance cost up front.

Push notifications were a one-line item on the roadmap. The line item was true. It just wasn't the whole shape.

The loop that changed how I write mobile tests

Amanda Gama — Sun, 03 May 2026 03:59:22 +0000

Mobile tests are where the bugs actually live. A signup flow that works on an iPhone 15 falls apart on a lower-end Android because the keyboard pushes a button off-screen. A push notification mid-flow leaves the app in a state nothing else reproduces. Memory pressure on a four-year-old Android does things you can't make a simulator do.

I wrote simulator-only tests anyway, for years. Real-device runs took ten to thirty minutes per cycle, the device farm queue was unpredictable, and CI on physical hardware was expensive enough that someone always wanted to talk about cost. So tests got written for the simulator, the device-specific bugs found their way to production, and we caught them in Sentry instead of in CI.

The thing that changed wasn't a better device farm or a faster CI. It was Claude Code writing the tests, BrowserStack MCP driving the devices, and the whole loop closing inside a single session. Claude writes a test, BrowserStack runs it on an actual iPhone, Claude reads the failure (screenshot, view tree, error trace) and fixes the test. Then it runs again. The cycle is under a minute. I never opened the test file.

That's the post. The tools matter, but what changed test authoring was the loop closing fast enough that I could stay in it.

The shape that changed

The mental model is simple. Old loop: write a test, push, wait for CI, read logs, guess at the failure, fix, push again. Best case ten minutes per iteration, often half an hour. Most of the wait is travel time: uploading the build, queuing for a device, tearing down. Almost none of it is the test itself.

New loop: Claude writes a test, the BrowserStack MCP runs it on a real device that's already provisioned, Claude reads the structured failure (screenshot, accessibility tree, console output, error stack), edits the test, runs it again. End-to-end under a minute on the happy path.

The speed isn't the value. The value is that the loop stays tight enough to stay in. Ten-minute iterations mean you context-switch out and come back cold. Sub-minute iterations mean the same problem is still in your head when the next result lands. You think about the test, not about what you were doing while you waited for CI.

The MCP is mostly invisible in this. It's just "Claude can drive real devices the way it drives anything else."

What the loop actually looks like

The clearest example was when I asked Claude to build an onboarding flow test from scratch: fresh install through to the home screen, with sign-up, email verification, and a multi-step intro along the way.

I described it in plain English. Claude wrote the first version: a script with the steps, selectors pulled from the screenshot it took on app launch, and an assertion at each milestone. It started a session on an iPhone 15, ran the test, and the test failed at step two.

The failure was a selector ambiguity. There were two elements matching [name="email"]: the visible field and a hidden form used for autofill detection. Claude saw both in the accessibility tree, picked the wrong one, and the typed text vanished into the hidden one. The test waited for the "verify your email" screen and timed out.

Claude fixed the selector to getByRole('textbox', { name: 'Email address' }) and re-ran. Past step two. Failed at step four. The third onboarding screen has an animated transition, and the tap on the next button fired before the animation finished, so the tap landed on a different element underneath. Claude added a wait on the transition end. Past step four. Eventually green.

Then I asked it to run the same test on a lower-end Android. Same code, different device. Failed on step three. The email verification deep link opens differently on Android. The Gmail app intercepts before the browser does, and the test was driving Chrome. Claude rewrote the verification step to use an alternative verification strategy for tests instead of clicking the link in the email. Re-ran on both devices. Green on both.

This whole sequence took maybe fifteen minutes. I didn't open a test file. I read every diff in the chat, said "yes" or "wait, why" three or four times, and the test ended up in the repo. The thing that made it work wasn't any single capability. It was that I could stay in the loop the whole time.

Where my role moved

I wasn't writing test code. I was reading it.

The most useful thing I did was catch the moments where Claude "fixed" a test by making it less strict. The pattern I learned to watch for: a test starts failing intermittently, Claude adds a wait longer than the original timeout, the test goes green. The wait isn't fixing flakiness. The wait is hiding it.

The cleanest example was a test that asserted the home screen rendered within 200ms after login. It started failing on the lower-end Android. Claude bumped the wait to ten seconds, the test passed, and we moved on. I caught it in review: the home screen was actually taking five seconds to render on that device because of an image-decode regression that had landed two days earlier. The test was supposed to catch exactly that. The "fix" deleted the catch.

This is the part the "LLM writes the tests" pitch always undersells. Claude is fast enough at authoring that it'll write a hundred tests in the time it would take me to write ten. Most of those tests are fine. Plenty pass because they assert close to nothing. If you don't read them, you ship a green suite that catches nothing, which is worse than no suite at all.

The bottleneck moved from authoring to judgment. Authoring is the part Claude is fast at. Judgment (does this test catch the right thing, is this assertion meaningful, is this wait masking a regression) is the part that's still mine. The work didn't disappear. It changed shape.

The MCP setup is where the time went

The loop only works when the MCP layer is reliable. When it isn't, you spend the day debugging the harness instead of writing tests.

The first day was almost entirely setup. BrowserStack credentials, MCP server config, tool permissions in Claude Code, the allowed device pool, network rules for the test backend. Each piece is documented somewhere. None of them are documented in the same place. I had four tabs open the whole time.

The tool surface is the bigger thing to plan for. The BrowserStack MCP exposes a finite set of actions: start session, run command, take screenshot, fetch logs. Most of what you want maps onto that cleanly. A few things don't. Driving a native permission dialog on iOS isn't a clean MCP action; you end up wrapping platform-specific helpers or carving a backdoor into the app for tests. Anything biometric is off the table without that backdoor.

Session lifetime caught me twice. BrowserStack sessions time out after a fixed window, devices disconnect under load, and the queue backs up during US business hours. The loop has to survive a session dying mid-test. I added a thin wrapper that re-acquires the device when the MCP returns a session-ended error and retries from the last clean assertion. That wrapper isn't optional. Without it, every long test run had a 30% chance of dying for no reason related to the code under test.

Permissions in Claude Code itself were the smaller surprise. By default, Claude asks before each tool call. The fiftieth time it asks to call the same BrowserStack action is the moment you regret it. I set a permission rule allowing that specific tool without prompts, and the loop got noticeably tighter. Skip this and you spend the day clicking "yes."

None of that is the loop changing test authoring. It's the boring tax for getting there. But it's a real day or two of setup, and skipping it in this post would be misleading. The pitch is "Claude writes the tests"; the reality is "Claude writes the tests after you spend a day making the harness work."

What you actually get

Coverage we wouldn't have written by hand. The cost of writing a test dropped enough that the question stopped being "is this worth a test" and started being "is this worth reading." We added tests for flows we'd been ignoring for years (the edge paths, the rare-but-real failure modes) because the marginal cost was small enough not to argue about.

Real-device coverage in CI, instead of simulator-only with prayers. The lower-end Android catches the things the iPhone 15 doesn't. The 200ms-versus-five-second image regression I mentioned earlier would have shipped if the test had stayed on a simulator.

The hidden cost is the one I keep coming back to: you have to read what Claude writes. If you don't, you accumulate tests that pass without testing anything, and the suite stops being a signal. The discipline shifts from authoring to reviewing. Most teams assume whoever writes the test is the one reviewing it. That works when writing is the slow step. When writing is fast and reviewing is the slow step, the assumption breaks. I haven't seen many teams notice yet.

It's not autonomous. The day it is, the discipline that survives won't be writing tests. It'll be deciding which ones still mean something.

Migrating a legacy React app from webpack to Vite

Amanda Gama — Sun, 03 May 2026 02:57:49 +0000

The codebase was old. React 16 with class components everywhere. React Router v3 with routes-as-children. A webpack 4 config that had been edited by a dozen people over five years and contained loaders nobody could explain. The dev server took 45 seconds to come up. Hot reload was 8 seconds on a good day, 20 on a bad one. The production build was 6 minutes. CI deploys took 14 minutes end to end.

I'd been dismissing Vite for two years. "Webpack works." It did work. It was also bleeding an hour a day off the team in dev server restarts, slow HMR cycles, and CI queues piling up behind each other.

Here's the catch: you don't migrate a legacy webpack project to Vite on its own. You end up migrating webpack, React, React Router, your test runner, and half your dependencies, because the things that make Vite fast are the same things that won't tolerate code from 2018. This post is about what that actually looks like.

What Vite actually does differently

The mental model shift is small, but it changes everything that follows.

Webpack bundles your app before serving it. Every dev server start walks the dependency graph, compiles every module it touches, links them, and produces a bundle. The bigger your app, the longer the wait, and it scales linearly. HMR is fast in theory, but in practice the graph invalidation is heavy enough that a 200ms code change turns into a 4-second rebuild.

Vite serves source files directly to the browser as native ES modules. Your App.tsx is requested by the browser, transformed on demand by esbuild, and sent back. Nothing gets bundled in dev. The cost of starting the server is the cost of starting a Node process plus reading config, not the cost of compiling your app.

For production, Vite uses Rollup. Bundling still happens, just not in the dev loop where it hurts.

webpack dev:    parse all -> compile all -> bundle -> serve
vite dev:       start server -> compile what the browser asks for

That's the whole insight. Everything else is a consequence.

The numbers

The dev server times told the story I expected:

Metric	webpack	Vite
Cold start	42s	1.1s
HMR (small change)	4-8s	50-200ms
Full reload	6-9s	400ms

The build times were less dramatic but still real:

Metric	webpack	Vite
Production build	5m 40s	1m 50s
Type check (separate)	45s	45s

The interesting part is type checking. Vite doesn't type-check your code. It strips types with esbuild and trusts you. If you want type safety in CI, you run tsc --noEmit separately. That stays exactly as slow as it was. So don't expect Vite to magically speed up TypeScript. It makes the transformation faster, not the checking.

What CI actually looked like before and after

The CI deploy was the win I didn't expect. Total deploy time went from 14 minutes to 5. The build itself only accounted for about 4 minutes of that improvement. The other 5 minutes came from second-order effects:

Smaller Docker layer. Rollup tree-shakes more aggressively than my webpack config ever did. Bundle size dropped 18%, and the image pushed faster.
No more cache thrashing. Webpack's persistent cache was 800MB, and CI was spending 90 seconds restoring it every run. Vite doesn't need one.
Parallel-friendly. Type check, lint, and build can run as three independent jobs. With webpack, the build dominated everything else, so splitting was pointless.

CI cost dropped about in line with wall-clock time. Not surprising, but watching the bill go down felt good.

The migration itself

The webpack-to-Vite swap on its own is a two-day job. On a legacy codebase, you don't get that luxury. The whole thing took closer to three weeks once you count the React upgrade, the router rewrite, and the test runner change that came along with it.

Start with the easy part: the build tool config.

Install:

npm install --save-dev vite @vitejs/plugin-react

A minimal vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    port: 3000,
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
  },
})

The index.html moves to the project root and becomes the entry point, not a template anymore. That's a real shift. Webpack treated HTML as an output. Vite treats it as the input. Your script tag points at your TS entry directly:

<script type="module" src="/src/main.tsx"></script>

Once that clicks, half the config changes make sense.

What came along for the ride

This is the part the tutorials skip. Vite assumes a modern stack. A legacy app doesn't have one, and that gap is where most of the real work hides.

React itself. React 16 will technically run under Vite, but @vitejs/plugin-react expects the new JSX transform that landed in React 17. You can pin an older plugin and limp along, or take the upgrade. I took the upgrade. Going to React 18 was straightforward once the build was clean, and Strict Mode caught a handful of effect bugs that had been hiding for years. Class components keep working. They just look increasingly out of place next to everything else.

React Router. This was the biggest single chunk of work. v3's API (routes-as-children, browserHistory as a singleton, onEnter hooks for auth) is just not compatible with v6's declarative <Routes> and useNavigate. There's no codemod that does it cleanly. I migrated in stages:

// v3
<Router history={browserHistory}>
  <Route path="/" component={App}>
    <Route path="users/:id" component={UserPage} onEnter={requireAuth} />
  </Route>
</Router>

// v6
<BrowserRouter>
  <Routes>
    <Route path="/" element={<App />}>
      <Route path="users/:id" element={<RequireAuth><UserPage /></RequireAuth>} />
    </Route>
  </Routes>
</BrowserRouter>

The mechanical translation is easy. The painful part is everywhere the old code reached into the router imperatively: browserHistory.push() from a saga, withRouter HOCs wrapping class components, route lifecycle hooks doing data fetching. Each one needs a real rewrite.

Budget honestly for this. The router upgrade took longer than the actual Vite swap.

Babel plugins you forgot you had. The old webpack config was running half a dozen Babel plugins for proposal-stage syntax that's been in the language for years: optional chaining, nullish coalescing, class properties. esbuild handles all of those natively, so you can delete them. But if any plugin was doing real work (a custom transform, an i18n extractor, an instrumentation pass), that has to become a Vite plugin or move to a separate step.

The dependency graveyard. Every legacy project has one. A charting library that hasn't published since 2019. A date picker pinned to a specific patch version. A state library the company forked internally. Anything shipping pure CommonJS without an exports field is going to fight Vite's dep optimizer. Some you can pre-bundle. Some need replacing. A few you'll end up patching with patch-package because the maintainer is gone.

Vite-specific gotchas

Beyond the legacy upgrade work, these are the traps that hit any webpack-to-Vite migration:

Environment variables. process.env.FOO becomes import.meta.env.VITE_FOO, and only variables prefixed with VITE_ are exposed to the client. That's a security feature (webpack would happily leak any env var you referenced), but it broke about 40 references in my codebase. Find-and-replace is your friend.

Dynamic imports with variable paths. This works in webpack and breaks in Vite:

const mod = await import(`./locales/${locale}.json`)

Vite needs to know the set of possible matches at build time. Use import.meta.glob:

const modules = import.meta.glob('./locales/*.json')
const mod = await modules[`./locales/${locale}.json`]()

CommonJS dependencies. Vite is ESM-first. Most modern packages are fine. Older ones with module.exports need optimizeDeps.include to pre-bundle them. Otherwise you get cryptic "default export" errors at runtime, and they only show up in production, because dev doesn't bundle.

Jest doesn't speak Vite. If you used jest with babel-jest configured to match webpack, your test setup is now misaligned with your build. The cleanest path is Vitest, which shares Vite's transform pipeline. The migration is mostly mechanical (describe, it, expect are the same), but the mocking syntax differs from Jest in spots. Budget half a day.

Public path / base URL. If your app is served from a subpath, webpack's publicPath becomes Vite's base. Forget this and you get a working dev build and a broken production deploy. I learned that one the hard way.

What didn't get better

Bundle analysis is worse. Webpack's analyzer ecosystem is mature. Vite's is fine, but less detailed. If you spend real time tuning bundle size, you'll feel the gap.

The plugin ecosystem is smaller. Most things you need exist, but expect to occasionally write a Rollup plugin where webpack would've had three options.

SSR setup is more hands-on. Vite supports it, but you wire it together yourself. If you were running a framework on top of webpack that handled SSR for you, switch to a framework on top of Vite (Remix, Next, SvelteKit) instead of doing it raw.

Was it worth it

For a greenfield project, Vite is a no-brainer. For a legacy app, it's messier. You're not just swapping a build tool. You're paying down years of tech debt because Vite forces you to. That's a feature, not a bug. Just budget for it honestly.

The dev experience win paid for itself the first week the team was on the new stack. After years of training your muscle memory to tolerate slow HMR, watching it feel instant is a small daily joy.

The deploy time win mattered more than I expected. Halving CI meant we merged to main more often, which meant smaller PRs and faster review cycles. That compound effect over a quarter was bigger than the raw numbers suggest.

The hidden win was the dependency cleanup, and I didn't see it coming. The migration forced a real audit of every package in package.json. A third of them were dead code or had modern replacements. The codebase that came out the other side was lighter and easier to onboard onto, and that part had nothing to do with Vite directly.

If you're on legacy webpack and your dev server takes more than 20 seconds to start, migrate. Just don't pitch it to your manager as a two-day job. It's a quarter of modernization work with a fast build tool at the end of it, and the payoff keeps showing up long after you're done.

Working remotely, the parts that actually mattered

Amanda Gama — Sun, 03 May 2026 02:51:28 +0000

I've been working remotely for a while, and most of what I picked up in the first six months turned out to be wrong, or wildly overrated. Not bad advice exactly. Most of it sounds reasonable when you read it. It just isn't doing the work it claimed to. The "wake up at 5am, dedicate a workspace, use the Pomodoro technique, journal every morning" stack is a kind of theater. Some of it helps a little. Most of it is energy you spend trying to feel productive instead of being productive.

What actually helped was less visible. Almost all of it was about removing small frictions, not adding discipline. The good weeks came from making fewer parts of the day cost mental energy. Not from squeezing more output out of willpower.

Here's what's stuck.

Your setup matters, but most of it doesn't

The setup advice you find online tends to confuse two different things: gear that looks good on your desk and gear that actually changes how you work. The list that genuinely helped me is short and boring.

A second monitor. This is the only piece of "setup" I'd call non-negotiable. Doing most knowledge work on a single laptop screen is the equivalent of writing in a notebook with the previous page glued shut.

A chair you can sit in for six hours without your back giving notice. You don't need the $1,500 ergonomic one. You need one that doesn't make you fidget by 3pm.

A decent headset. Not for the audio quality, though that helps. For the "I'm wearing headphones" signal that lets you ignore the world without feeling rude. The mic built into most laptops is fine.

Enough light. Especially in winter, especially for video calls. A cheap overhead light plus something at face level is the floor.

Things that didn't change anything for me: a mechanical keyboard, a fancy webcam, a standing desk, a third monitor, cable management trays, a "cozy" lamp, a houseplant. Some of those are nice. None of them changed how much I got done. If you're spending more than a weekend setting up your workspace, you're probably procrastinating with extra steps.

Routines beat motivation, but lighter than you'd think

The hardcore routine content (wake at 5am, cold shower, journal, gym, deep work block before email) is impressive on Instagram and unsustainable in real life. I tried versions of it. The version that survived was much smaller.

Two rituals, one rule.

The first ritual is a fixed start. Same first action every morning, regardless of what's on the calendar. For me it's coffee plus ten minutes reviewing what I want to get done before lunch. Not the whole day. Just the morning. The point isn't planning. It's the transition from "not working" to "working," so you don't burn the first hour ramping up.

The second is a fixed end. Before closing the laptop, write down the first task you'll start tomorrow. One sentence, on paper or in a note. This sounds stupid until you realize how much energy you waste at the start of every day re-deriving where you left off.

The rule is: don't open Slack first thing. Anything genuinely urgent will still be urgent in 90 minutes. The first block of the day is the only one where you reliably have full focus, and burning it on reactive replies is the single biggest productivity leak I had to fix.

What I gave up: time-blocking the whole day, color-coded calendars, hourly check-ins with myself, gratitude journals. Not because they're bad, but because for me they were maintenance overhead disguised as productivity.

Communication is half the job

The thing nobody really warns you about is how much of remote knowledge work is writing. Slack messages, PR comments, design docs, status updates, weekly summaries. If you can't write reasonably clearly, remote work is going to be harder than it was in the office, where tone and presence covered a lot of gaps.

A few things I've changed:

I default to written updates over meetings. The standing weekly check-in I used to do is now a five-bullet update I write on Friday afternoons. Read in two minutes, no scheduling cost, searchable for later. The meetings I keep are the ones that need actual discussion. Not status, not "alignment," not "syncing."

I'm slow to reply on purpose. If you answer every Slack within ten minutes, you've trained the team to use you as a synchronous resource, which is the opposite of remote. An informal four-hour SLA on non-urgent threads is usually enough to let people figure things out themselves before pinging.

I write outcomes, not activities. "Shipped the new auth flow" is useful. "Worked on auth all afternoon" isn't. Everyone's calendar is full of work; what people actually want to know is what came out of it.

I avoid the 15-minute "quick sync." It's never quick. Either it's a question that could be answered in writing in three minutes, or it's a real conversation that deserves 30 minutes and a doc. The middle case mostly doesn't exist, and treating it like it does is how a calendar gets eaten.

Protect deep work like it's a billable hour

Two hours of uninterrupted focus is more valuable than eight hours of fragments. This is the most-repeated and most-ignored piece of remote-work advice. It's true, and most people (me included, until recently) treat it as aspirational rather than enforceable.

Here's what actually works:

Two-hour blocks on the calendar, marked busy, treated as real meetings. Not "focus time." That's too vague to defend against your own future self. Specific: "Architecture review draft: do not book over."

Notifications off during those blocks. Slack quit, email closed, phone in another room. The phone-in-another-room thing sounds dramatic; it's the single change that made the biggest difference for me. Reaching for the phone to "check something" was costing me twenty minutes per occurrence and I wasn't tracking it.

One context switch (a non-urgent message, a notification, a quick check of something) costs around twenty minutes of lost focus on hard work. Not because the switch is long, but because the climb back is. If you understand that and still switch, fine. Most of us don't, and the cost compounds across the day.

The hardest part is letting things sit. Replies waiting, threads moving, a question someone just asked. All of it can wait until your block is done. That's the muscle.

When you add travel to the mix

I've been working remotely while traveling for stretches, and the honest version is that travel makes most of the above harder, not easier. The Instagram pitch (laptop on a beach, perfect productivity) is selectively true on a small number of days, and it costs you on most of the others.

The things that get harder, in rough order of how much they hurt. Time zones first. You're either disconnected from your team for half the day, or answering Slack at midnight. Then internet. A hotspot stops being optional and becomes the actual connection in most places. Then environment. A different desk, different chair, different noise floor every week or two. The compounding effect of "decent enough" beats the effect of "novel" within about a month.

What helps, if you do it anyway: pick places with infrastructure first and aesthetics second. Carry a backup hotspot on a different carrier. Don't try to start work the day you arrive somewhere new. The first 24 hours is logistics, not output. Protect at least four hours of overlap with your team, wherever you are.

What you give up is real: deeper rest, a stable rhythm, a setup that gets a little better every month. Travel is fun. It's also a tax on output. If the location is the point, you'll love it. If the work is the point, you'll find that traveling less makes the work easier, which is worth knowing before you sign a six-month lease somewhere far away.

What I've stopped believing

A few things I dropped along the way.

That gear matters much beyond the basics. It doesn't.

That every hour of the day needs to be productive. Most of mine aren't, even on good days, and trying to force them just adds anxiety to the unproductive ones.

That working from "cool" places makes you happier. It makes the photos better. The day-to-day feels about the same.

That async means everything has to be in writing. Some conversations need to be conversations. Trying to write your way through every disagreement, every nuanced design call, every piece of feedback is its own kind of overhead.

That discipline is the answer. Most days, removing one source of friction beats adding one new habit. The version of remote work that lasted, for me, has fewer rules than the version I started with, and the ones that remain are mostly about what I don't do.

Clean architecture in React Native isn't about layers

Amanda Gama — Fri, 01 May 2026 03:46:40 +0000

Every React Native codebase I've worked on hits the same wall around month four. A screen that started at 80 lines is now 400. Half of it is useEffect chains coordinating API calls. A push notification mid-flow leaves the app in a state nobody can reproduce.

Clean architecture in React Native isn't about folders or layers. It's about whether you can still reason about your app when async, navigation, and native modules collide.

The shape that fails

The default React Native architecture is "everything lives where it's first needed." API calls land in the handler that triggers them. State sits in the screen that displays it. Native modules get called from the button that activates them. It works for the first month.

What it doesn't survive:

Async outliving its caller. A user kicks off a request, taps a notification, lands on a different screen. The original promise resolves into a setter that no longer makes sense.
Native modules in the UI. A screen calls NativeModules.Audio.start() directly. iOS 17 changes the audio session semantics. Three screens break, not one.
Auth races. A token refresh fires while three other requests are in flight. Two retry, one logs the user out, one leaks the old token.
Drift. The same "send a message" logic lives in two screens. One gets a validation rule added. The other doesn't.

The pattern that produces all of this:

const handleSend = async () => {
  const res = await api.post('/messages', input)
  setMessages(prev => [...prev, res.data])
}

Nothing wrong with this code on its own. The problem is the second time it gets written, slightly differently, in another screen.

Three layers, one rule

Skip the diagram. The minimum viable framing:

Presentation. Screens, components, hooks. Renders. Orchestrates.
Domain. Use cases. Pure logic. No react, no fetch, no NativeModules.
Data. API clients, storage, native bridges. Knows about the outside world.

One rule: the UI talks to the domain, never to data directly.

That's the post. The rest is what enforcing that rule does to the bugs above.

Use cases are the boundary

The shift in code is small:

// Before: handler decides how things work
const handleSend = async () => {
  const res = await api.post('/messages', input)
  setMessages(prev => [...prev, res.data])
}

// After: handler delegates
const handleSend = async () => {
  await sendMessage.execute(input)
}

The use case is where the logic actually lives:

class SendMessage {
  constructor(private repo: MessageRepository) {}

  async execute(input: SendMessageInput) {
    // validation, business rules, orchestration
    return this.repo.send(input)
  }
}

This isn't ceremony. The point is that SendMessage is the only place anyone outside the domain learns how a message gets sent. Two screens calling it can't drift apart, because there's only one of it.

The repository is the other half:

interface MessageRepository {
  send(input: SendMessageInput): Promise<Message>
}

The use case depends on the interface. The implementation lives in the data layer. The UI imports neither. It imports the use case, calls execute, and stops thinking.

Where React Native makes you pay for shortcuts

This is the part most "clean architecture" posts are silent on. Web apps have UI and API. React Native has UI, API, navigation lifecycle, native modules, background/foreground transitions, and OS-level interruptions. The cost of mixing layers compounds with each one.

Async outliving the screen. A request starts on screen A and resolves after the user is on screen C. If the resolution reaches for component-local setters, navigation refs, or context that no longer exists, you get a bug that only reproduces when someone moves fast. A use case gives you one place to attach cancellation, idempotency, or "is this caller still listening?" guards. The screen doesn't need to know.

Native modules don't belong in handlers. NativeModules.Audio.start() in a button handler ties the UI to platform behavior. Platform behavior is the part most likely to diverge between iOS and Android, between OS versions, between simulator and device. Wrap the module in a repository, expose a use case (StartRecording), and the UI is platform-agnostic. The platform-specific logic has one home, and you know where to look when iOS changes.

Auth and rehydration races. Token refresh overlapping with three in-flight requests is the canonical React Native bug. If your auth logic is split across an axios interceptor, a context provider, and a screen, the race is unfixable. There's no single thing to serialize. A RefreshSession use case that owns the queue makes it tractable. Boring, but tractable.

Tests stop pretending

The biggest practical payoff isn't reuse. It's that tests stop needing the framework.

it('sends a message via the repo', async () => {
  const repo = new FakeMessageRepo()
  const useCase = new SendMessage(repo)

  await useCase.execute({ body: 'hi' })

  expect(repo.sent).toHaveLength(1)
})

No render tree. No react-test-renderer. No mocked NativeModules. No Detox. The use case runs in pure Node and exits in milliseconds.

Most of the value of architecture is what becomes testable, not what becomes "clean."

The trap

A few ways this goes wrong:

Optional architecture isn't architecture. "I'll just call the API directly this once" is how you end up with three places that do the same thing badly. Either the boundary is enforced or it isn't.
Three layers for a two-screen app is waste. If your app is a login and a list, you don't need a use case layer. Apply this when the complexity earns it, usually somewhere between the third real feature and the second engineer.
Folders aren't boundaries. You can have a domain/ directory and still call fetch from a screen. The directory structure is documentation. ESLint rules and code review are enforcement.

The other cost is upfront friction. A new feature now touches three files instead of one. For a few weeks that feels worse, not better. It pays off the first time a bug reproduces only on Android, only after a notification, only when offline. You find the cause in one place instead of grepping six.

What you actually get

Clean architecture in React Native isn't a goal, and it isn't about being clean. Something will go wrong at month twelve, in a way you didn't predict. It's the bill you pay so the code you're staring at is still one you can reason about.

Going native for voice recording

Amanda Gama — Thu, 30 Apr 2026 16:21:53 +0000

When you build a recording feature in React Native, the obvious move is to reach for one of the popular audio libraries. I did. Then I tried another. Then a third.

Every one of them fell over on the same two scenarios: the OS backgrounding the app, and a memory warning while a long recording was in flight. Files would land on disk corrupt, half-finalized, or just gone. Internal state would desync from reality. There was no recovery hook. Once the lifecycle went sideways, you got back a false from a promise and that was the end of it.

A 90-second voice memo silently disappearing is a hard failure. I needed control of the audio session and the interruption surface. So I wrote my own native module.

The audio session config

The session setup is small but every flag earns its place:

- (BOOL)configureAudioSession:(NSError **)error {
    AVAudioSession *session = [AVAudioSession sharedInstance];

    BOOL success = [session setCategory:AVAudioSessionCategoryPlayAndRecord
                            withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker |
                                        AVAudioSessionCategoryOptionAllowBluetooth |
                                        AVAudioSessionCategoryOptionMixWithOthers
                                  error:error];
    if (!success) return NO;

    success = [session setMode:AVAudioSessionModeSpokenAudio error:error];
    if (!success) return NO;

    return [session setActive:YES error:error];
}

PlayAndRecord is the only category that lets me record and play back from the same module. DefaultToSpeaker keeps audio off the earpiece. Recordings get reviewed on speaker, not held to the ear. AllowBluetooth so AirPods users don't have to take them out. MixWithOthers so I don't kill the user's podcast or music when the recorder simply opens.

AVAudioSessionModeSpokenAudio pays for itself: iOS tunes signal processing for voice when it's set, and you can hear the difference on playback.

The catch: setActive: can fail on first call if another audio client is mid-handoff. A short sleep and one retry recovers from that race almost every time:

- (BOOL)configureAudioSessionWithRetry:(NSError **)error {
    if ([self configureAudioSession:error]) return YES;
    [NSThread sleepForTimeInterval:0.6];
    return [self configureAudioSession:error];
}

Surviving interruptions and memory warnings

This is the part the libraries got wrong.

AVAudioSessionInterruptionNotification fires when a phone call comes in, when Siri activates, when another app grabs the audio session. The default behavior is "your recorder stops, good luck." I pause cleanly, persist state, and emit an event back to JS so the UI can show "recording paused (call interruption)":

- (void)handleInterruption:(NSNotification *)notification {
    NSDictionary *info = notification.userInfo;
    AVAudioSessionInterruptionType type =
        [info[AVAudioSessionInterruptionTypeKey] unsignedIntegerValue];

    if (type == AVAudioSessionInterruptionTypeBegan) {
        if (audioRecorder && audioRecorder.isRecording) {
            [audioRecorder pause];
            [self stopProgressTimer];
            [self persistRecordingState];
            [self emitStateChange:@"paused"];
            [self emitInterruption:@"phone_call"];
        }
    }
}

When the interruption ends, I re-activate the session (with the same retry logic) and signal JS whether the system wants the recording resumed.

Memory warnings are the more interesting case. iOS will tear the process down without ceremony if pressure stays high. But the warning itself is a chance to land cleanly. I stop the recorder, which causes AVFoundation to finalize the M4A header so the partial file is playable, then emit a distinct state so the UI can offer recovery:

- (void)handleMemoryWarning:(NSNotification *)notification {
    if (audioRecorder && (audioRecorder.isRecording || isPaused)) {
        [self persistRecordingState];
        [audioRecorder stop];
        [self stopProgressTimer];
        [self sendEventWithName:@"onRecordingStateChange" body:@{
            @"state": @"stopped_memory_warning",
            @"filePath": currentFilePath ?: @"",
            @"reason": @"Recording stopped due to low memory."
        }];
    }
}

The libraries' failure mode here was silence. The OS killed them and the user lost the take. Stopping early with a finalized file on disk is a much better trade.

Level metering math

For a waveform UI, AVAudioRecorder gives you averagePowerForChannel: and peakPowerForChannel:. They return dBFS (full-scale referenced), so 0 dB is clipping and the floor is around -160 dB.

The math everyone gets wrong on the first try is the normalization. You can't just divide by 160. Real voice rarely registers below -50 dB; using the full range gives you a bar that lives in the bottom 10% of its travel and barely moves. Pick a practical floor (-50 works) and clamp:

[audioRecorder updateMeters];
float averagePower = [audioRecorder averagePowerForChannel:0];
float peakPower = [audioRecorder peakPowerForChannel:0];

float normalizedLevel = (averagePower + 50.0) / 50.0;
normalizedLevel = MAX(0.0, MIN(1.0, normalizedLevel));

float normalizedPeak = (peakPower + 50.0) / 50.0;
normalizedPeak = MAX(0.0, MIN(1.0, normalizedPeak));

I sample at 50 ms: NSTimer at 0.05 s on the main run loop. Faster looks jittery, slower looks laggy. 50 ms is also roughly the cadence the RN bridge can deliver events at without batching, so there's no point emitting more.

The boring numbers that matter

The recorder settings are a five-line dictionary, but each value is a deliberate choice:

- (NSDictionary *)audioRecorderSettings {
    return @{
        AVFormatIDKey: @(kAudioFormatMPEG4AAC),
        AVSampleRateKey: @44100.0,
        AVNumberOfChannelsKey: @1,
        AVEncoderAudioQualityKey: @(AVAudioQualityMedium),
        AVEncoderBitRateKey: @64000,
    };
}

AAC in an M4A container plays everywhere: iOS, Android, browsers. PCM/WAV is an order of magnitude bigger. Opus still has gaps on older Safari.

44.1 kHz over 48: a hair smaller on disk, and downstream voice pipelines will resample anyway. Mono halves file size again and matches reality. No one is recording a stereo voice memo.

64 kbps AAC at AVAudioQualityMedium is transparent for speech. Apple's own defaults sit at 128 to 256 kbps, which is overkill for voice and produces files four times bigger than they need to be.

What I got back

About 150 lines of Objective-C replaced three failed library integrations. The recorder now survives a phone call, a memory warning, and a backgrounded app, and emits structured events JS can react to instead of swallowing the failure.

I own this surface now, though. The libraries handled enough cases that you could ship without thinking about audio sessions at all; I chose to think about them, and that bill comes due whenever iOS changes interruption semantics. I accept it because the alternative was silently losing recordings.