DEV Community: Amit chakraborty

The Hermes Bytecode Trap: Why Your App is Fast in Development and Slow in Production

Amit chakraborty — Sat, 10 Oct 2026 04:30:04 +0000

I was the first engineering hire at Synapsis Medical Technologies, responsible for taking our HealthTech AI platform from zero to one. We were building a React Native application that integrated with clinical wearables and served real-time AI insights via a HIPAA-aligned RAG pipeline. On my local M2 MacBook, the app felt instantaneous. In our CI/CD pipeline—which I had just overhauled to cut release cycles from two days down to four hours—everything passed.

Then we pushed to a group of beta users in a clinical setting.

The symptom wasn't a crash; it was a "hang." Users on mid-range Android devices reported that the app would sit on the splash screen for six to eight seconds. Our TTI (Time to Interactive) metrics, which looked fine in the lab, spiked to unacceptable levels in the field. We were losing the "instant" feel required for a clinical tool.

The culprit wasn't our React code. It was a failure to properly manage the Hermes bytecode pre-compilation during the transition from development to production.

Why the "Hermes Boost" Fails Under Load

In development, Hermes acts as a Just-In-Time (JIT) engine. It parses JavaScript on the fly. In production, it switches to Ahead-of-Time (AOT) compilation. The build process transforms your JavaScript into .hbc (Hermes Bytecode) files.

The promise is that the device doesn't have to parse the JS; it just maps the bytecode into memory and executes. However, three things break this in production:

Instruction Cache Misses: If your bundle is massive (common in AI-heavy apps with large vendored libraries), the bytecode size can exceed the device's efficient memory mapping limits.
The Bridge Bottleneck: Even with Hermes, if you are initialising heavy native modules (like FHIR/HL7 parsers or encrypted local storage) on the main thread during the same tick as the Hermes VM startup, the UI thread will starve.
Bytecode Version Mismatch: If your CI/CD pipeline doesn't strictly align the Hermes compiler version with the specific Hermes runtime version bundled in your node_modules, the engine falls back to a slower execution mode or fails to load the pre-compiled bundle entirely.

The Fix: Step-by-Step

To solve this at Synapsis, I had to move beyond the default "enable Hermes" flag and implement a strict verification and optimisation pipeline.

1. Force Bytecode Alignment in CI

Never assume your build server is using the correct compiler. If you are on React Native 0.73+, the Hermes version is tied to the React Native version.

Verify your bytecode version by adding a check in your __tests__ or a pre-build script. Use the hermesc command-line tool to inspect the generated bundle.

# Locate the compiler in your node_modules
HERMESC_PATH="./node_modules/react-native/sdks/hermesc/%OS%-bin/hermesc"

# Compile a test file and check the bytecode version
$HERMESC_PATH -emit-binary -out ./test.hbc ./test.js
$HERMESC_PATH -dump-bytecode ./test.hbc | grep "Bytecode version"

Why: If the version in your package.json doesn't match the compiler used by your CI runner, you will see a format version mismatch error in Logcat, and the app will default to the much slower JS parsing.

2. Implement "Dead Code" Pruning for the VM

Hermes' memory footprint is directly tied to the number of functions it needs to register. In our AI platform, we had large JSON schemas for FHIR data.

The Action: Move static, large data structures out of the JS bundle and into native assets or fetch them on demand.
Confirmation: Monitor the index.android.bundle size. If it exceeds 10MB, your TTI on a device like a Samsung A50 will increase by ~500ms per additional MB due to I/O overhead.

3. Profile the "Quiet" Startup Failures

Use the Chrome DevTools protocol with Hermes to capture a .cpuprofile.

Open the app in release-mode-like conditions (but with debugging enabled).
Capture the profile from the very first millisecond of the Entry Point.
Look for HermesVM::init.

If you see a long gap between HermesVM::init and the first FunctionCall, your native modules are blocking the VM. In my experience, this is usually caused by synchronous calls to SharedPreferences or Keychain during the C++ initialization phase of the React Native bridge.

4. Enable Memory-Mapped I/O (mmap)

Ensure your Android build is actually using mmap for the bytecode. In your MainApplication.java (or MainApplication.kt), verify the JSExecutorFactory.

// Ensure you are using the default HermesExecutor, 
// but check if you have custom configurations that override the memory limit.
val factory = HermesExecutorFactory()

Confirmation: Use adb shell procrank while the app is starting. If USS (Unique Set Size) jumps instantly to 100MB+, your bytecode isn't being memory-mapped efficiently; it's being copied into RAM.

The Cost of the Fix

Optimising Hermes is not free.

Build Times: AOT compilation adds roughly 2-5 minutes to a clean build, depending on bundle size. In our CI/CD overhaul, we had to use distributed caching for the android/.gradle and ios/build folders to keep our 4-hour release cycle intact.
Debugging Difficulty: Bytecode stack traces are notoriously difficult to read. You must strictly manage your Source Maps. If you lose the source map for a specific bytecode build, production crashes will be impossible to trace.
The Trade-off: You are trading build-time CPU cycles for end-user battery life and TTI. For a clinical app, this is always the right choice.

At Your Level

Starting Out

Focus on ensuring Hermes is actually enabled. Check global.HermesInternal in your App.js. If it returns null, your configuration is wrong, and you're running on the old, slower JSC engine.

Working Engineer

Stop using console.log for performance timing. Use Performance.now() and track the time from the first line of index.js to the useEffect in your root component. If this is over 1000ms on a real device, you have a bundle initialization problem that Hermes alone won't fix.

Senior or Staff

You own the architecture. You must enforce a "bundle budget." If a new library adds 2MB to the bytecode, it must be justified by a 2MB removal elsewhere or a critical feature. Implement automated bundle size reporting in every Pull Request to catch regressions before they hit the 4-hour release window.

Lead or Director

Understand that TTI is a retention metric. At Synapsis, a 2-second delay in clinical AI insights could mean a clinician stops using the tool. Budget time for "performance sprints" where the team does nothing but prune dependencies and optimize the bridge.

In the Interview

The Question: "We've enabled Hermes, but our Android startup time is still poor. What do you investigate first?"

The Weak Answer: "I'd check the React code for heavy loops or unnecessary re-renders."

Why it's weak: Startup time (TTI) is rarely about React re-renders; it's about the time it takes to get the VM running and the first frame painted.

The Strong Answer: A senior candidate should point to the Bridge and the Bytecode. They should discuss the difference between JIT and AOT, the overhead of memory-mapping large .hbc files, and the potential for synchronous native module initialization to block the UI thread.

The Follow-up: "How do you handle the fact that Hermes doesn't support Intl on older versions of React Native?"

This separates those who have read the docs from those who have shipped. The answer involves polyfills that increase bundle size, directly impacting the TTI benefits Hermes provides. You have to weigh the cost of the polyfill against the speed of the engine.

Amit Chakraborty is a founding engineer and senior architect — React Native, AI/RAG systems and production architecture. Portfolio: www.amitchakraborty.dev · LinkedIn · GitHub. Open to senior and founding engineering roles, remote worldwide.

Defending the 16ms Frame: A Performance Budget for React Native Skia

Amit chakraborty — Fri, 09 Oct 2026 12:30:34 +0000

I was the first engineering hire at Synapsis Medical Technologies, where I eventually scaled the team to 21 engineers. We were building a HealthTech AI platform that required real-time visualisations of wearable data—ECG waveforms and live heart-rate variability—layered over a React Native UI.

We chose @shopify/react-native-skia because the standard React Native View hierarchy collapsed under the weight of 500+ data points updating at 60Hz. However, three weeks before a major clinical pilot, our "smooth" animations started stuttering. On an iPhone 15 Pro, it looked fine. On the mid-range Android devices our partner clinic used, the frame rate dropped to 22 FPS. The UI thread was clear, but the JavaScript thread was choking, and the GPU was waiting for data that arrived too late.

The cost was immediate: we couldn't pass the clinical usability audit. Stuttering waveforms in a medical context aren't just a "bad UX"—they look like equipment failure. We had to move from a vague "make it faster" mandate to a rigid performance budget that every engineer on the team had to defend.

Why Skia stutters in React Native

In React Native 0.76 and earlier, the bottleneck is rarely Skia’s C++ engine. It is the bridge or the JSI (JavaScript Interface) overhead.

When you use useDrawSelection or Canvas, every frame requires a trip from the JS thread to the UI thread. If you are calculating paths inside a standard useMemo and passing them as props to a Skia component, you are serialising data across the bridge. Even with the New Architecture (TurboModules), if your JS thread is busy with a heavy JSON parse or a RAG pipeline update—as was common in our AI workflows—the rendering instruction arrives late.

The "16ms budget" (for 60fps) or "8ms budget" (for 120fps) isn't just for drawing. It includes:

JS Execution: Calculating the new coordinates.
JSI Transfer: Moving that data to the Skia host objects.
Rasterization: Skia actually drawing pixels.

If JS takes 12ms, you have only 4ms left for everything else. On a low-end Android device, Skia might need 10ms to rasterize a complex blur or a heavy path, putting you at 22ms total—well over the 16ms limit.

The Fix: Implementing the 16ms Ceiling

We moved from "best effort" rendering to a "budget-first" architecture. Follow these steps to lock down your rendering performance.

1. Externalise State to Skia Values

Stop using useState or useSharedValue from Reanimated for high-frequency Skia updates. Use Skia.makeMutable or useValue from the Skia library itself. This keeps the data within the Skia engine's reach without triggering React render cycles.

How to confirm: Open the React DevTools profiler. If your Skia component shows a re-render count matching your frame rate, you have failed this step. The component should render once, and the Skia Value should update the drawing internally.

2. Offload Path Generation to a Worklet

Generating a complex SVG path string in JS is expensive. For our ECG waveforms, we shifted path generation to useComputedValue.

// Do not do this in the main body of the component
const path = Skia.Path.Make();
points.forEach((p, i) => {
  if (i === 0) path.moveTo(p.x, p.y);
  else path.lineTo(p.x, p.y);
});

// Do this instead
const path = useComputedValue(() => {
  const p = Skia.Path.Make();
  // ... logic here
  return p;
}, [pointsValue]);

Why: This ensures the path is built as a host object. You are passing a reference across the JSI, not a massive string or array of coordinates.

3. Establish the "Frame-Drop" Metric

We integrated react-native-performance to track js_fps and ui_fps. I set a CI gate: if the 95th percentile of frame time exceeded 16ms on a Galaxy A54 (our baseline low-end device), the PR was blocked.

The Command:
Use the Flashlight CLI (a tool for mobile performance measurement) to get an actual score:
flashlight measure --bundleId com.synapsis.app --duration 10000

Look for the "Frame Duration" metric. If the mean is >16ms, you are dropping frames.

4. Use Picture Recording for Static Overlays

If your UI has complex gradients or shadows that don't change every frame (like a background grid), do not redraw them. Use SkPicture.

const picture = useMemo(() => {
  const recorder = Skia.PictureRecorder();
  const canvas = recorder.beginRecording(rect);
  // Draw complex, static background here
  return recorder.finishRecording();
}, []);

// In your draw function
canvas.drawPicture(picture);

How to confirm it worked: Use the Skia Overlay (<SkiaDomView debug />). You will see the "Draw Calls" count drop significantly. In our case, it dropped from 140 calls to 12 per frame.

The Cost of a Performance Budget

Enforcing a 16ms budget has trade-offs that aren't always pleasant:

Development Velocity: It took my team roughly 30% longer to ship new visual features because they couldn't just "drop a component in." They had to architect the data flow to avoid the bridge.
Code Complexity: You end up with "Skia-specific" state management that sits parallel to your Redux or Zustand store. Synchronising these two can lead to bugs where the UI shows one value while the Skia canvas shows another.
Hardware Ceiling: There is a point where a device simply cannot render what you want. We had to implement "Feature Degradation"—detecting low-end GPUs and disabling Gaussian blurs or reducing the sample rate of the ECG waveform from 250Hz to 125Hz.

At your level

Starting out:
Stop using setInterval or requestAnimationFrame to drive animations. Use useTiming or useLoop from @shopify/react-native-skia. The one thing to do next: move one useState value that drives a Skia element into a useValue hook and observe the reduction in React re-renders.

Working engineer:
Profile your app using the Flashlight CLI on a physical Android device, not an iOS simulator. The simulator uses your Mac's GPU and will lie to you about performance. Your goal is to keep the "JS Thread" usage below 40% during animations to leave headroom for background tasks.

Senior or staff:
Architect a "Layered Rendering" strategy. Move static elements to the standard React Native View hierarchy (which is heavily optimised by the OS) and only use Skia for the volatile, high-frequency pixels. The one thing to do next: implement a PerformanceMonitor provider that samples frame times and automatically downgrades graphical fidelity (e.g., removing BlurMask) for users on older devices.

Lead or director:
Define the "Baseline Device." If you don't name a specific $200 Android phone as your target, your engineers will develop on $1,200 iPhones and ship a product that fails in the real world. Budget for a "Performance Sprint" every quarter where no features are added, only frame-time regressions are fixed.

In the interview

The Question: "How do you handle a performance bottleneck in a React Native app with complex graphics?"

Weak Answer: "I would use useMemo to cache calculations and make sure I'm not doing too much on the JS thread." (Too vague; doesn't acknowledge the specific constraints of the bridge or the GPU).

Strong Answer: A strong answer identifies the JSI bridge as the primary bottleneck. You should discuss the trade-off between Declarative API (easier to read, higher overhead) and the Imperative API (manual drawing, lower overhead). Mention specific tools like Flashlight or Perfetto for tracing.

Senior Follow-up: "How do you handle the synchronisation between a Skia animation and a React Native FlatList scroll?"
The Answer: This probes for knowledge of thread synchronisation. A senior candidate should explain that since Skia rendering happens on the UI thread (if using the right hooks), it can be perfectly synced with onScroll events using useSharedValue and useDerivedValue, provided you avoid the jump back to the JS thread. They should mention the risk of "checkerboarding" if the JS thread is too slow to feed the list while the GPU is busy drawing Skia layers.

Measuring the ROI of TurboModules before you commit to the rewrite

Amit chakraborty — Fri, 09 Oct 2026 08:30:03 +0000

I was leading the architecture for a clinical AI platform at Synapsis Medical Technologies, where we were integrating real-time health data from wearables into a React Native environment. We were hitting a wall with the Bridge. As we scaled to handle high-frequency biometric streams, our UI thread started dropping frames during heavy data ingest.

The immediate internal pressure was to migrate everything to TurboModules and the New Architecture (React Native 0.76+). The promise of synchronous execution and type-safe Codegen is seductive. However, I had a team of 21 engineers and a product roadmap that didn't include a month of "architectural refactoring" with no visible feature output.

If you blindly migrate a stable Native Module to a TurboModule, you might spend 40 hours of engineering time to save 2ms of overhead that wasn't your bottleneck. I’ve shipped 18 production apps, and the most expensive mistake I see is optimising for architectural purity rather than measured latency.

Before you touch codegen, you need to know if the Bridge is actually your problem.

Why the Bridge fails under load

In the legacy architecture, every call between JavaScript and Native is asynchronous, serialised as JSON, and passed over a single queue.

When we were streaming data from a wearable heart-rate monitor, each data point was a Bridge message. If the user was also interacting with a complex UI—say, a real-time graph—the Bridge became a bottleneck. The symptom wasn't just "slowness"; it was non-deterministic lag. The JSON serialisation overhead for a large array of health metrics can take 5–10ms. When you do that 60 times a second, your message queue backs up, and your onPress events stay stuck behind data packets.

TurboModules solve this by using JSI (JavaScript Interface), allowing JS to hold a reference to C++ host objects. You move from "sending a letter" (Bridge) to "calling a function" (JSI). But if your module only fires once every 10 seconds—like a battery level check—the Bridge overhead is irrelevant.

The fix: Step-by-step instrumentation

Do not start by changing your C++ or Java code. Start by profiling the actual cost of the Bridge in your current production build.

1. Trace the Bridge Traffic

You need to see the volume and frequency of messages. Use the built-in MessageQueue spy. In your entry file (e.g., App.js), add:

import MessageQueue from 'react-native/Libraries/BatchedBridge/MessageQueue';

if (__DEV__) {
  MessageQueue.spy(true);
}

Why: This logs every call between JS and Native to your console.
Confirm: Watch the console during the specific user action that feels slow. If you see a flood of calls to the same module (e.g., DeviceEventManager.emit), you have a high-frequency bottleneck. If you see very large JSON payloads, you have a serialisation bottleneck.

2. Measure Bridge Latency with Systrace

Standard console logs don't show you the time spent in the serialisation layer. Use the react-native-performance library or the built-in Profiler in Flipper.

Open Flipper and select the React Native Tracers.
Start a trace and perform the heavy action.
Look for the Bridge or JS Call markers.

Confirm: Look for gaps where the JS thread is idle but the Native thread is busy, or vice versa. If the "Bridge" bar is consistently wider than 5ms per call, the overhead is significant enough to justify a TurboModule.

3. Define the Codegen Spec

If the data proves you need to move, start with the Spec. This is the "contract" that ensures type safety. Create a file named Native[YourModuleName].ts in a specs folder.

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  readonly getHealthData: (id: string) => Promise<string>;
  readonly streamData: (values: number[]) => void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('YourModuleName');

Why: Codegen uses this TypeScript interface to generate the C++ glue code (JSI) and the Java/Objective-C boilerplate.
Confirm: Run node node_modules/react-native/scripts/generate-codegen-artifacts.js. If it fails, your types aren't compatible with the restricted subset of TypeScript that Codegen supports (e.g., you cannot use generic any or complex unions).

4. Implement the Synchronous Method

One of the primary reasons I move to TurboModules is for synchronous methods. In the old Bridge, everything returned a Promise. In TurboModules, you can return a value directly.

In your native implementation (e.g., YourModule.mm for iOS):

- (NSString *)getHealthData:(NSString *)id {
  return @"Synchronous Data"; 
}

Confirm: Call the method in JS: const data = YourModule.getHealthData('123');. If it returns the value immediately without an await, the JSI layer is working.

What it costs, and when not to do it

The cost of TurboModules is primarily in build-time complexity and developer experience.

Build Times: Codegen adds a significant overhead to your build process. In our CI/CD overhaul, where I cut release cycles from 2 days to 4 hours, we found that poorly managed native builds could add 10 minutes just to the compilation phase of a clean build.
C++ Requirement: To get the full performance benefit, you often end up writing C++ (via JSI). If your team is purely JS/React, you are introducing a massive bus-factor risk.
Library Compatibility: Many third-party libraries still rely on the Bridge. Mixing the New Architecture with legacy modules requires the "Interop Layer," which can introduce its own performance regressions.

Do not migrate if: Your app is a standard CRUD app where the most complex thing you do is fetch a JSON API and display it in a list. The Bridge is more than fast enough for 90% of applications.

At your level

Starting out

Focus on understanding why MessageQueue.spy() exists. Before you learn how to write a TurboModule, learn how to read the Bridge traffic. If you can identify a "chatty" bridge, you've already provided more value than someone who just follows a tutorial.

Working engineer

Implement a performance monitoring suite. Don't wait for a bug report. Use react-native-performance to track bridge_transfer_time in your staging environment. The goal is to have a baseline so you can prove the ROI of a rewrite to your lead.

Senior or staff

Your job is to prevent the migration until it is necessary. Evaluate the "Interoperability Layer" cost. If you have 50 legacy modules, moving one to TurboModules might actually slow down the app due to the overhead of the New Architecture's compatibility bridge. Own the decision of when to flip the switch for the entire repo.

Lead or director

Consider the hiring implications. Moving to a JSI-heavy architecture means you need engineers who understand the memory management differences between JS and C++. If you don't have that talent or the budget to hire it, stick to the Bridge and optimise your JSON payloads instead.

In the interview

The Question: "We are seeing UI stutters when processing high-frequency data from a native sensor. How do you decide between optimising the Bridge or moving to TurboModules?"

Weak Answer: "TurboModules are faster because they use JSI and the New Architecture, so we should migrate to get better performance." This is weak because it assumes the architecture is the bottleneck without proof and ignores the massive engineering cost of migration.

Strong Answer: A strong answer starts with measurement. You should discuss using the MessageQueue spy to check for "chattiness" and measuring the serialisation overhead. You would mention that the Bridge overhead is usually around JSON stringification/parsing. If the frequency of calls is the issue, you might first try batching the data on the native side before it hits the Bridge.

The Senior/Staff Follow-up: "What happens if we have a mix of TurboModules and legacy modules?"
A senior candidate must discuss the Interoperability Layer. They should know that the New Architecture has to wrap legacy modules to make them compatible, which can actually increase memory pressure. They should be able to explain that the real win of TurboModules isn't just "speed," but the ability to perform synchronous calls to native code, which eliminates the need for complex async state management in some UI interactions.

Production failures: the things that page you · 2. Thundering herd: when the cache expires all at once

Amit chakraborty — Fri, 09 Oct 2026 04:30:11 +0000

Production failures: the things that page you · Chapter 2 of 24 · Reliability · new chapter every Friday morning

By the end of this chapter: Recognise correlated cache expiry and apply jitter and request coalescing.

The problem

Say you are an engineer on call for a content API. A celebrity mentions your site, and traffic spikes to ten times its normal volume. You open your dashboards, applying the structured reading method from Chapter 1, and the symptom is clear: the primary Postgres database is pegged at 100% CPU. Connections are maxed out, and the API is returning 503s.

You check the cache hit rate. It is normally 95%, but right now it is oscillating wildly between 99% and 0%. You assume the cache time-to-live (TTL) is too short, so you deploy a change increasing it from five minutes to thirty minutes. The database recovers instantly. You close the incident. Thirty minutes later, the pager goes off again with the exact same database CPU spike.

You have built a thundering herd. When a cache key expires under heavy load, hundreds of concurrent requests all miss the cache at the exact same millisecond. They all query the database simultaneously. The database stalls, connections queue up, and the API drops requests. Increasing the TTL did not fix the problem; it just delayed the next synchronised failure by thirty minutes.

Before you start

You need a local Redis server and Node.js.

Node.js 20.x or higher.
Redis 7.2 or higher.
The redis npm package (v4.6.x).

Verify your environment by running this in your terminal:

node -v && redis-cli ping

You should see v20.x.x (or higher) and PONG. If redis-cli is not installed, ensure your Redis server is running on the default port (6379).

Why does a fixed TTL synchronise traffic?

A cache with a fixed TTL acts as a traffic synchroniser. If a popular item is not in the cache, the first request fetches it from the database and writes it to Redis with a TTL of exactly 300 seconds.

For the next 299 seconds, the database does no work for that item. The API serves thousands of requests directly from Redis. But exactly 300 seconds later, the key evaporates. If your API is handling 500 requests per second for that item, all 500 requests in that specific second will check Redis, find nothing, and query the database.

The database does not see a smooth average of traffic. It sees zero requests for five minutes, followed by a wall of 500 concurrent queries, followed by zero requests for another five minutes. If those 500 queries require complex joins, the database CPU spikes, queries time out, and the API fails.

How do we decouple the expiry?

You prevent synchronised expiry by adding jitter. Jitter is randomness applied to a fixed interval.

Instead of caching an item for exactly 300 seconds, you cache it for 300 seconds minus a random percentage—usually up to 20%. One request might set a TTL of 281 seconds, the next 245 seconds, the next 299 seconds.

When you apply jitter to a large number of cached items, they no longer expire simultaneously. The database load smooths out. However, jitter only prevents different keys from expiring at the same time. It does not stop 500 concurrent requests from hitting the database when a single, highly popular key expires.

How do we handle concurrent misses?

To protect the database from a single popular key expiring, you must implement request coalescing, also known as single-flight.

When 500 requests ask for the same missing key, only the first request should query the database. The other 499 requests should wait for the first request to finish, and then share its result.

In an asynchronous language like JavaScript, you do this by caching the Promise of the database call in memory, rather than just the final result. When a request comes in, it checks the in-memory map. If a Promise exists for that key, the request awaits it. If not, it creates the Promise, puts it in the map, and queries the database.

Build it

We will build a Node.js script that simulates 50 concurrent requests for a single item that is not in the cache. We will implement both request coalescing and TTL jitter so the database is only queried once.

Step 1: Initialize the project
Create a new directory and install the Redis client. This client handles the connection to your local Redis server.

npm init -y
npm install redis@4.6.10

Step 2: Write the coalescing cache implementation
Create a file named index.js and paste the following code.

const { createClient } = require('redis');

const redis = createClient();
redis.on('error', err => console.error('Redis Client Error', err));

// The in-memory map that holds pending database calls
const pendingRequests = new Map();

// A simulation of a slow database query
async function queryDatabase(id) {
    console.log(`[DB] Executing expensive query for ${id}...`);
    return new Promise(resolve => 
        setTimeout(() => resolve(`Data for ${id}`), 1000)
    );
}

async function getWithCoalescingAndJitter(id, baseTtlSeconds) {
    const cacheKey = `item:${id}`;

    // 1. Check the distributed cache (Redis)
    const cached = await redis.get(cacheKey);
    if (cached) {
        return cached;
    }

    // 2. Check for an in-flight request (Coalescing)
    if (pendingRequests.has(cacheKey)) {
        console.log(`[Cache] Coalescing request for ${id}`);
        return pendingRequests.get(cacheKey);
    }

    // 3. Fetch from DB, cache it, and clean up the pending map
    const promise = (async () => {
        try {
            const data = await queryDatabase(id);

            // Calculate jitter: subtract up to 20% from the base TTL
            const jitter = Math.floor(Math.random() * (baseTtlSeconds * 0.2));
            const finalTtl = baseTtlSeconds - jitter;

            await redis.set(cacheKey, data, { EX: finalTtl });
            console.log(`[Cache] Wrote to Redis with TTL ${finalTtl}s`);

            return data;
        } finally {
            // Always remove the promise, whether it resolved or rejected
            pendingRequests.delete(cacheKey);
        }
    })();

    // Store the promise so subsequent requests can await it
    pendingRequests.set(cacheKey, promise);
    return promise;
}

async function run() {
    await redis.connect();
    await redis.flushAll();

    console.log("Firing 50 concurrent requests...");

    // Fire 50 requests at the exact same time
    const promises = Array.from({ length: 50 }).map(() => 
        getWithCoalescingAndJitter('user-1', 300)
    );

    const results = await Promise.all(promises);

    console.log(`Completed ${results.length} requests.`);
    console.log(`First result: ${results[0]}`);

    await redis.disconnect();
}

run();

Step 3: Run the code and verify the output
Execute the script.

node index.js

You should see output similar to this:

Firing 50 concurrent requests...
[DB] Executing expensive query for user-1...
[Cache] Coalescing request for user-1
[Cache] Coalescing request for user-1
... (repeated 49 times)
[Cache] Wrote to Redis with TTL 284s
Completed 50 requests.
First result: Data for user-1

Notice that despite 50 requests firing simultaneously, the [DB] log only appears once. The other 49 requests found the pending Promise in the map and waited for it. The TTL was set to 284 seconds, demonstrating the jitter subtracting from the 300-second base.

When this breaks

Symptom: Memory usage on the application servers grows linearly until the process crashes with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory.
Cause: The pendingRequests map is leaking Promises. This happens if a database call hangs indefinitely without a timeout, or if the code that removes the Promise from the map is inside a .then() block rather than a finally block. If the database call rejects, the .then() block is skipped, the Promise stays in the map forever, and all future requests for that key will await a rejected Promise.
Fix: Always use a finally block to delete the key from the coalescing map, as shown in the implementation above. Enforce strict timeouts on the database queries themselves.

Symptom: Redis throws OOM command not allowed when used memory > 'maxmemory'.
Cause: You implemented jitter by adding a random amount of time to the base TTL, rather than subtracting it. If your base TTL was tuned to exactly fit your available Redis memory, adding 20% to the TTL increases the total number of keys stored at any given moment by 20%, breaching your memory limit.
Fix: Always calculate jitter by subtracting from the maximum acceptable TTL. The base TTL should represent the absolute longest you are willing to serve stale data.

Symptom: The database still sees a thundering herd, just a smaller one.
Cause: In-memory request coalescing only protects the database from concurrent requests hitting the same application instance. If you run 100 Node.js containers, and a popular key expires, each container will allow one request through to the database. You will still see 100 concurrent database queries.
Fix: For moderate scale, 100 queries is acceptable and in-memory coalescing is sufficient. For massive scale, you must implement distributed coalescing using Redis locks, ensuring only one container globally is allowed to query the database for a missing key.

What it costs

Request coalescing trades database CPU for application memory and open connections.

When you coalesce 500 requests, 499 of them are sitting in your application server doing nothing but holding open HTTP connections to your clients, waiting for the single database query to resolve. If the database query takes five seconds, you are holding 500 connections open for five seconds. Under heavy load, this can easily exhaust your application server's connection limits or memory, causing it to drop traffic before it even reaches the coalescing logic.

This commits you to keeping your database queries fast. Coalescing is a shield against concurrent load, not a band-aid for slow queries. If the underlying query is inherently slow, you should not be coalescing requests; you should be pre-computing the cache asynchronously in a background worker so the API never has to wait for the database at all.

In the interview

When an interviewer asks, "How do you protect a database from a sudden traffic spike?", they are probing your understanding of cache failure modes.

A weak answer is, "I would put a Redis cache in front of it." This is weak because it assumes caches never expire and never start empty. It demonstrates that the candidate has read about caching but has not supported a high-traffic cache in production.

A strong answer names the failure mode: "I would use a cache, but I'd need to protect against a cache stampede or thundering herd when keys expire." A senior candidate will explain how they use jitter to prevent correlated expiry windows, and request coalescing to handle concurrent misses.

If you are interviewing for a Staff or Director role, the interviewer is probing your grasp of trade-offs. The follow-up will be: "What happens to the application servers while they wait for the coalesced request?" A successful answer acknowledges the cost: holding those requests consumes memory and connections. The candidate should then pivot to discussing stale-while-revalidate patterns or background cache warming as superior architectural alternatives that avoid holding client connections open entirely.

Your tasks

Observe the herd: Modify the index.js script. Comment out the coalescing check (step 2 in the function). Run the script again. You should see 50 [DB] logs, simulating 50 concurrent database queries. This is the failure mode you are preventing.
Break the cleanup: Restore the coalescing check. Remove the finally block entirely. Modify the queryDatabase function to throw an error for user-2. Fire a request for user-2, catch the error, and then fire a second request for user-2. Verify that the second request hangs forever because the rejected Promise is permanently stuck in the pendingRequests map.
Implement stale-while-revalidate: Modify the implementation so that if the cache has expired, but the data is still in Redis (you will need to store the insertion timestamp inside the cached JSON), the function immediately returns the stale data to the user, but fires the database query in the background to update Redis for the next user.

Your tasks this week

Do the exercises above before the next chapter. Reading a tutorial and doing
one are different activities and only one of them changes what you can build.

Stuck on any of them? Say so — describe what you tried and what happened:
tell me where you got stuck. I read every one, and the questions
that come back more than twice get answered in the next chapter.

Production failures: the things that page you

Chapter 2 of 24. New chapter every Friday morning.
Next: Retry storms.

· The full syllabus and every chapter so far
· Subscribers also get the condensed notes for this chapter, the running
recap of everything the series has covered, and the extended guidance:
subscribe

Written by Amit Chakraborty — founding engineer and senior architect: React Native, AI and RAG systems, production architecture. Portfolio · LinkedIn · GitHub.

Need this built, reviewed or taught to your team? Get in touch or email amit@devamit.co.in. Available for senior and founding engineering roles, consulting and training, remote worldwide.

Why Your Lighthouse Score is Lying About Your Core Web Vitals Regression

Amit chakraborty — Fri, 09 Oct 2026 04:30:03 +0000

I was monitoring the Vercel dashboard for a Next.js clinical AI platform I built at Synapsis Medical Technologies when the Interaction to Next Paint (INP) metric for our patient portal spiked from 180ms to 450ms. In a HIPAA-compliant environment where clinicians rely on real-time RAG (Retrieval-Augmented Generation) responses, a 300ms delay isn't just a "yellow" warning in a report—it is the difference between an interface feeling responsive and a user double-clicking a button, potentially triggering duplicate API calls to an LLM pipeline.

I ran Lighthouse. The score was a perfect 100. I ran a manual Trace in Chrome DevTools on my M3 Max MacBook; the main thread was clear. Yet, the field data—the real-world experience of patients on three-year-old Android devices and spotty hospital Wi-Fi—showed a catastrophic regression.

We spent two days chasing phantom layout shifts before identifying that the regression wasn't in our code, but in how we were measuring it. If you rely on lab data (Lighthouse/Synthetic) to debug production regressions, you are looking at a curated, sterile version of your app that does not exist for your users.

The Gap Between Lab and Field

Lab data is a snapshot in a controlled environment. Field data (Chrome User Experience Report or CrUX) is the messy reality. At Synapsis, I oversaw the architecture of five production systems, and the most expensive lesson I learned was that a "Performance" score in a CI/CD pipeline is a vanity metric.

Field regressions usually stem from three causes that lab tests cannot simulate:

Device Heterogeneity: Your CI runner has a fast CPU; your user is on a $200 Motorola.
Network Jitter: Lab tests use simulated throttling, which is predictable. Real-world 4G has packet loss that wreaks havoc on hydration.
User Interaction: Lighthouse doesn't click buttons. INP, which replaced FID (First Input Delay), only exists when a user interacts.

Step 1: Isolate the Population, Not the Page

When a regression hits, do not look at the aggregate score. A 200ms jump in Largest Contentful Paint (LCP) across your entire site is often a false signal caused by a change in traffic mix (e.g., a new marketing campaign hitting lower-end devices).

What to do: Open your Real User Monitoring (RUM) tool—whether that is Vercel Speed Insights, Datadog RUM, or a custom web-vitals library implementation. Filter the regression by device type and connection type.

How to confirm: If the LCP regression only appears on "4G" and "Mobile" but "Desktop" remains flat, your issue is likely image encoding or a bloated JavaScript bundle that is choking lower-end CPUs during decompression, not a server-side logic error.

Step 2: Identify the "Attribution" Element

The biggest mistake I see leads make is guessing which element caused a Cumulative Layout Shift (CLS). The documentation tells you what CLS is; it doesn't tell you that the "offending" element in the console is often the victim, not the cause.

What to do: Use the web-vitals JavaScript library to log the attribution object to your analytics provider.

import { onCLS } from 'web-vitals/attribution';

onCLS((metric) => {
  console.log(metric.attribution.largestShiftTarget); 
  // Send this string to your logging service
});

How to confirm: Look for the largestShiftTarget in your logs. In one instance, our "regression" was actually a third-party cookie consent banner that loaded 2 seconds late. Lighthouse missed it because the headless browser didn't trigger the consent flow.

Step 3: Debugging INP with Long Animation Frames (LoAF)

If your INP has spiked, the standard "Performance" tab in DevTools is often too noisy. You need to see what is blocking the main thread at the exact moment of interaction.

What to do: Enable the "Long Animation Frames API" in your testing. If you are on Chrome 123 or higher, you can use the Long Animation Frames (LoAF) entry to see exactly which script contributed to the delay.

Open DevTools -> Performance.
Click the "Interactions" track.
Look for the red bars.
Identify the "Presentation Delay."

How to confirm: If the "Input Delay" is high, your main thread was busy when the user clicked. If the "Processing Duration" is high, your event listener code is slow. If "Presentation Delay" is high, the browser was struggling to paint the frame (often due to excessive DOM size or complex CSS).

The Cost of Over-Optimisation

At Synapsis, I oversaw a CI/CD overhaul that cut release cycles from 2 days to 4 hours. Part of that was removing "Performance Gatekeeping" in CI that relied on Lighthouse scores.

Why? Because forcing an engineer to fix a 2-point Lighthouse drop in a PR often leads to "hacks" like delaying the load of essential scripts (like analytics or support chats) until after the first interaction. This improves the lab score but destroys the field INP, as the main thread suddenly hits a wall the moment the user tries to use the app.

The trade-off is simple: Lab data is for catching catastrophic failures before they merge; Field data is for making business decisions. Never roll back a release based solely on a Lighthouse score if your RUM data remains stable.

At Your Level

Starting out

Stop using "Fast 3G" throttling in DevTools as a proxy for reality. It is a linear slowdown. Instead, use the "Network" tab to simulate offline and slow speeds, but focus on understanding the "Main Thread" work in the Performance tab. Your goal is to see how your code execution blocks the browser.

Working engineer

Implement the web-vitals library with attribution. You cannot fix what you cannot name. When a ticket comes in for "slowness," your first response should be to pull the largestShiftTarget or the processingDuration for that specific user session.

Senior or staff

Own the RUM strategy. You should be looking at the 75th and 95th percentiles (P75/P95). A regression in P95 often signals a memory leak or a specific edge case (like a very large FHIR resource loading into a state manager), while a regression in P75 signals a general architectural bloat.

Lead or director

Distinguish between "Performance" as a technical metric and "User Experience" as a business one. A 500ms LCP increase is acceptable if it comes from high-resolution product images that increase conversion by 10%. Do not let your team spend 40 hours chasing a green score if the business metric is moving in the right direction.

In the Interview

The Question: "Our LCP has regressed by 1 second in production, but Lighthouse shows no change. How do you find the cause?"

The Weak Answer: "I would check the images, minify the CSS, and maybe try to implement a CDN or use next/image." This is weak because it jumps to solutions without diagnosing why the tools are giving conflicting signals.

The Strong Answer: A strong candidate identifies that Lighthouse is a synthetic environment and the regression is likely environment-dependent. They will talk about Field vs. Lab data. They will mention checking CrUX reports or RUM data to segment by device and geography. They will specifically name Interaction to Next Paint (INP) as a metric that Lighthouse cannot accurately measure.

The Senior Follow-up: "How do you handle a third-party script that is tanking your INP but is required by the marketing team?"
This separates those who have read docs from those who have shipped. A senior engineer knows you can't always delete the script. They will discuss requestIdleCallback, using Partytown to move scripts to a Web Worker, or strategically yielding to the main thread using setTimeout(..., 0) to break up long tasks. They understand the organizational friction between performance and third-party requirements.

MLOps: models that survive production · 2. Data versioning

Amit chakraborty — Thu, 08 Oct 2026 16:30:07 +0000

MLOps: models that survive production · Chapter 2 of 12 · AI Engineering · new chapter every Thursday night

By the end of this chapter: Reproduce a training run from six months ago.

The problem

Say you are an engineer who has just been asked to retrain the churn prediction model from Q1. A new enterprise customer needs it deployed in their own environment, but with a slight tweak to the output format. You check out the Git tag release-q1, run the training script, and wait.

The original run logged an F1 score of 0.88. Your new run logs 0.64.

You have not changed a single line of code. The random seeds are pinned. The dependencies are locked in a requirements file. But the data in s3://company-ml-data/churn/latest.csv is from today. Since Q1, the upstream engineering team has added three new columns, changed the definition of an 'active user', and dropped all rows from a deprecated region.

You spend three days trying to manually reconstruct the Q1 dataset from database backups. You fail. You have to explain to your lead that the model currently running in production cannot be rebuilt, audited, or modified, because the data it was trained on no longer exists.

Before you start

You need a terminal, Python, Git, and DVC (Data Version Control).

Install DVC via pip. Do not use Homebrew or apt for this; keeping DVC in your Python environment ensures your CI pipeline and your local machine run the same version.

pip install dvc==3.48.4

Verify the setup. This command must return a version number for both tools:

git --version && dvc --version

Create a new directory for this exercise and move into it:

mkdir churn-model && cd churn-model

Why Git cannot hold your data

The instinct when faced with this problem is to put the data in Git alongside the code. If the code and data are in the same commit, checking out the commit restores both.

Git is designed for text. It tracks changes line by line. If you commit a 5GB CSV file, Git will attempt to compress it and store the delta. It will fail to do this efficiently. Your .git directory will balloon. Cloning the repository will take hours. Eventually, you will push to GitHub, which will reject any file larger than 100MB, and you will have to rewrite your Git history to remove the commit.

Git Large File Storage (LFS) is the standard workaround in software engineering, but it fails in machine learning. Git LFS tightly couples your data storage to your Git provider. If you have 5TB of training data, storing it in GitHub LFS is prohibitively expensive compared to an AWS S3 bucket. Furthermore, Git LFS lacks the semantics for data pipelines; it cannot tell you if a dataset was generated by a specific script, only that the file changed.

You need Git to track the exact state of your data, without Git ever touching the data itself.

The pointer file pattern

To solve this, we use the pointer file pattern. This is the mechanism underlying DVC.

Instead of committing dataset.csv to Git, you hash the file's contents. You store the heavy dataset.csv in a dumb object store (like S3, or just a hidden folder on your laptop) renamed to its hash, for example a1b2c3d4.csv.

Then, you create a tiny text file called dataset.csv.dvc. This file contains nothing but the hash a1b2c3d4 and the file size. You commit this tiny text file to Git.

Git tracks the code and the pointer. DVC tracks the heavy file. When you check out a Git commit from six months ago, Git updates dataset.csv.dvc to contain the old hash. You then tell DVC to read that pointer, find the corresponding heavy file in the object store, and copy it back into your workspace.

Code and data are synchronised, but Git only handles text.

Build it

We are going to create a dataset, version it, overwrite it with new data, and then successfully time-travel back to the original state.

Step 1: Initialise the repositories
Initialise Git, then initialise DVC. DVC will create a .dvc directory to act as your local object store.

git init
dvc init

DVC creates some internal configuration files. Commit them to Git so your repository is clean.

git commit -m "Initialise DVC"

Step 2: Generate the Q1 data
Create a Python script named generate_data.py to simulate our Q1 dataset.

# generate_data.py
import csv

def write_data(filename, rows):
    with open(filename, 'w', newline='') as f:
        writer = csv.writer(f)
        writer.writerow(['user_id', 'active_days', 'churned'])
        writer.writerows(rows)

# Q1 Data
write_data('dataset.csv', [
    [1, 15, 0],
    [2, 3, 1],
    [3, 20, 0]
])
print("Wrote Q1 data to dataset.csv")

Run it:

python generate_data.py

Step 3: Track the data with DVC
Tell DVC to track the CSV file.

dvc add dataset.csv

Look at the output. DVC tells you exactly what to do next:

To track the changes with git, run:
    git add dataset.csv.dvc .gitignore

When you ran dvc add, DVC did three things:

It calculated the MD5 hash of dataset.csv.
It moved dataset.csv into .dvc/cache/ under its hash name, and put a hard link back in your workspace.
It created dataset.csv.dvc (the pointer) and updated .gitignore so you do not accidentally commit the raw CSV to Git.

Step 4: Commit the pointer to Git
Commit the code, the pointer, and the gitignore file. This creates our Q1 snapshot.

git add generate_data.py dataset.csv.dvc .gitignore
git commit -m "Train Q1 model"
git tag release-q1

Step 5: Generate the Q2 data
Time passes. The definition of the data changes. Modify generate_data.py to output the Q2 data. Change the rows and add a new column.

# generate_data.py
import csv

def write_data(filename, rows):
    with open(filename, 'w', newline='') as f:
        writer = csv.writer(f)
        # Schema change: added 'region'
        writer.writerow(['user_id', 'active_days', 'region', 'churned'])
        writer.writerows(rows)

# Q2 Data
write_data('dataset.csv', [
    [4, 30, 'EU', 0],
    [5, 2, 'US', 1],
    [6, 45, 'EU', 0]
])
print("Wrote Q2 data to dataset.csv")

Run it to overwrite the CSV:

python generate_data.py

Step 6: Track and commit the Q2 data
Update DVC with the new file, then update Git with the new pointer.

dvc add dataset.csv
git add generate_data.py dataset.csv.dvc
git commit -m "Train Q2 model"

If you open dataset.csv now, you will see the Q2 data with the region column.

Step 7: Time travel
You are asked to reproduce the Q1 model. First, check out the old Git commit using the tag we made.

git checkout release-q1

Look at dataset.csv. It has not changed. It still contains the Q2 data.

This is the most common point of confusion. Git only updated the text files it tracks. It updated generate_data.py and it updated the pointer file dataset.csv.dvc. It did not touch the actual CSV.

To synchronise your workspace with the pointer file, run:

dvc checkout

Output:

M       dataset.csv

Open dataset.csv again. The region column is gone. The data is exactly as it was in Q1. You can now run your training script and get the exact 0.88 F1 score you got six months ago.

When this breaks

The file is modified but dvc checkout does nothing
You manually edited dataset.csv to fix a typo. You realise you made a mistake, so you run dvc checkout to restore the file to the state of the pointer. Nothing happens. The typo is still there.

DVC uses file timestamps and sizes to optimise checkouts. If you edit a file in place without changing its size enough, DVC might not realise it has changed. To force DVC to verify the hashes and overwrite your local modifications, use:

dvc checkout --force

ERROR: unexpected error - .dvc/cache is not tracked by git
You cloned your repository to a new machine, ran dvc checkout, and got an error about a missing cache or a missing file.

ERROR: failed to pull data from the cloud - Access Denied

The .dvc/cache directory is in your local .gitignore. It does not push to GitHub. When you clone the repository, you get the pointers, but not the heavy files. To get the heavy files, you must configure a DVC remote (like an S3 bucket) using dvc remote add, push the data there from the original machine (dvc push), and pull it on the new machine (dvc pull). If you get Access Denied, your AWS credentials in your terminal session do not have s3:GetObject permissions for that bucket.

Git merge conflicts in .dvc files
You and a colleague both updated the dataset on different branches. When you merge, Git throws a conflict in dataset.csv.dvc.
A .dvc file is just YAML containing a hash. You cannot merge hashes. You must pick one. Accept either your changes or their changes in the Git merge tool. Then, whichever one you picked, run dvc checkout to ensure your local CSV matches the hash you just committed to the merge.

What it costs

This approach costs storage space, and it scales poorly for append-only data.

Because DVC hashes the entire file, it does not do delta compression for tabular data. If you have a 10GB CSV file and you append one row, dvc add will hash the new file, copy the entire 10GB into .dvc/cache, and update the pointer. You are now storing 20GB of data. If you do this every day for a month, you are storing 300GB of redundant data.

For datasets that update frequently, flat-file versioning with DVC is the wrong tool. You are paying the storage cost of full duplication. In those scenarios, you must move to a time-travel database format like Apache Iceberg or Delta Lake, which version data at the row or block level, or rely on a Feature Store.

DVC is best used for unstructured data (images, audio) where files are immutable and added discretely, or for tabular data that is generated as a distinct, immutable artifact for a specific training run.

It also costs developer friction. Every data change now requires two commands (dvc add, then git add). If you forget dvc add, you will commit a stale pointer to Git, and your CI pipeline will train on old data while your Git history claims otherwise.

In the interview

When an interviewer asks, "How do you ensure your training runs are reproducible?", they are checking if you understand that code is only half the state of an ML system.

A weak answer focuses entirely on the environment: "I set the random seeds, pin the requirements, and use Docker." This is weak because it assumes the data is static. In production, data is a moving target. If you run the same Docker container against a database that has changed, the output changes.

A strong answer explicitly names the pointer file pattern. "I version the code, the environment, and the data. I use a tool like DVC to hash the training artifacts, store them in an object store, and commit the pointer files to Git. This guarantees that checking out a Git commit restores the exact bytes of data used for that run."

If you are interviewing for a Senior or Staff role, the interviewer will probe the limits of this. They will ask what happens when the dataset is 500GB and updates daily. A senior candidate must immediately identify the storage duplication trade-off. You should explain that DVC is for artifact versioning, not database versioning. For daily updates at scale, you would advocate for Delta Lake to query the data "as of" a timestamp, or a Feature Store that guarantees point-in-time correctness, rather than hashing flat files.

The follow-up question that separates practitioners from theorists is: "What happens if someone modifies the data file but forgets to run dvc add before committing to Git?" The practitioner knows exactly what happens: the Git commit contains the old hash, the new data is left untracked in the workspace, and anyone pulling the repository will get the old data, silently invalidating the training run.

Your tasks

Configure a local remote. By default, DVC stores the heavy files in .dvc/cache. Create a new directory outside your Git repository (e.g., mkdir /tmp/dvc-remote). Use dvc remote add -d myremote /tmp/dvc-remote to configure it. Run dvc push. Delete your local .dvc/cache directory, then run dvc pull. Verify dataset.csv is restored.
Break the sync. Open dataset.csv and manually change a value. Do not run dvc add. Run dvc status. It will tell you the file is modified. Use the DVC CLI to discard your manual changes and restore the file to match the Git pointer.
Read the pointer. You do not strictly need the DVC CLI to know what data a Git commit used. Write a three-line Python script that opens dataset.csv.dvc, parses it as YAML (or just string splits it), and prints the MD5 hash. This is how CI systems verify data without downloading the whole DVC binary.

Your tasks this week

Do the exercises above before the next chapter. Reading a tutorial and doing
one are different activities and only one of them changes what you can build.

MLOps: models that survive production

Chapter 2 of 12. New chapter every Thursday night.
Next: Features: stores, and the simpler thing that usually works.

Written by Amit Chakraborty — founding engineer and senior architect: React Native, AI and RAG systems, production architecture. Portfolio · LinkedIn · GitHub.

Need this built, reviewed or taught to your team? Get in touch or email amit@devamit.co.in. Available for senior and founding engineering roles, consulting and training, remote worldwide.

Defending the 16ms Frame: A Performance Budget for React Native TurboModules

Amit chakraborty — Thu, 08 Oct 2026 16:30:03 +0000

I was the first engineering hire at Synapsis Medical Technologies, where I owned the architecture for a HealthTech AI platform from day zero. We were integrating real-time health data from wearables and running HIPAA-aligned RAG pipelines. During a critical phase of our scaling—where I grew the team from zero to 21 engineers in 13 months—we hit a wall.

We were building a clinical dashboard that needed to stream high-frequency biometric data. On the old Bridge architecture, the serialisation overhead was killing us. Frames were dropping, the UI felt "heavy," and our clinical users—doctors who don't have patience for laggy interfaces—started complaining. We had moved to React Native 0.76 to leverage the New Architecture, but simply "using TurboModules" didn't fix the jank.

The problem wasn't the technology; it was the lack of a ceiling. We were treating native calls as "free" when they were actually the most expensive part of our render loop. I had to implement a strict performance budget to stop the team from inadvertently shipping 100ms blocks to the main thread. This moved us from a vague "make it faster" mandate to a measurable 16.6ms frame budget that we defended in every PR.

The Cost of the Invisible Bridge

In the legacy architecture, the Bridge was a bottleneck because of asynchronous JSON serialisation. TurboModules solve this by using JSI (JavaScript Interface), allowing direct C++ communication. However, I’ve found that developers often treat JSI as a license to move massive amounts of data frequently.

If you pass a 5MB clinical dataset over JSI every 100ms, you won't see a "Bridge Busy" warning, but you will see the JavaScript thread stall while the C++ layer handles the memory allocation. In our case, the cost was a two-day release cycle that I eventually cut to four hours by automating the validation of these boundaries. If the codegen didn't match the performance spec, the build failed.

Why JSI isn't a silver bullet

The documentation tells you how to write a Spec file and run node-modules/.bin/react-native codegen. It doesn't tell you that C++ handles memory differently than JavaScript's garbage collector.

When you define a TurboModule, you are creating a synchronous contract. If your native method takes 20ms to execute, your JavaScript thread is frozen for 20ms. You have just dropped a frame. On a 60Hz display, you have 16.6ms to do everything. If your TurboModule takes 10ms, you have 6.6ms left for React rendering, layout, and event handling. That is a razor-thin margin.

The Fix: Implementing a Codegen Performance Budget

This approach ensures that native modules are not just "fast," but "predictably fast."

1. Define the Strict Spec with Primitive Types

Avoid passing generic Object or Array types in your TypeScript specs. Every time JSI has to iterate over a generic object to find a key, you lose microseconds. Be explicit.

In your NativeBiometricScanner.ts:

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  // BAD: getHeartRateData(): Object; 
  // GOOD: Explicit primitives reduce JSI conversion overhead
  getHeartRateData(patientId: string): {
    readonly bpm: number;
    readonly confidence: number;
    readonly timestamp: number;
  };
}

export default TurboModuleRegistry.getEnforced<Spec>('NativeBiometricScanner');

Why: Codegen uses these types to generate C++ structs. Primitives map directly to C++ types (double, bool, std::string). Generic objects require a jsi::Object lookup, which is significantly slower under load.

2. Instrumented Codegen Execution

Don't just run the codegen; wrap it in a script that validates the generated C++ glue code for "fat" signatures. I used a simple grep-based check in our CI/CD pipeline to flag any TurboModule using jsi::Value or jsi::Object where a primitive could have been used.

# Run codegen
node node_modules/react-native/scripts/generate-codegen-artifacts.js \
  --path ./ \
  --outputPath ./generated

# Confirm it worked: Check for forbidden generic types in the generated Header
if grep -q "jsi::Object" ./generated/NativeBiometricScannerSpec.h; then
  echo "Error: Generic Object detected in TurboModule Spec. Use explicit types."
  exit 1
fi

3. The 16ms Telemetry Wrapper

You cannot manage what you do not measure. We wrapped our TurboModule calls in a telemetry utility. If a call exceeded 8ms (half our frame budget), it triggered a warning in our staging environment.

const start = performance.now();
const data = NativeBiometricScanner.getHeartRateData('pt-123');
const end = performance.now();

if (end - start > 8) {
  console.warn(`TurboModule Budget Exceeded: getHeartRateData took ${end - start}ms`);
}

The Number: In my experience, a single TurboModule call should ideally take less than 2ms. If you are seeing 8ms+, you are either passing too much data or doing heavy computation on the caller's thread instead of a background thread.

4. Offloading to Background Threads

If the telemetry shows you are over budget, you must move the work. TurboModules are synchronous by default, but you can return a Promise which moves the execution to a native background thread.

In your Objective-C++ or C++ implementation, ensure you aren't blocking RCTQueue. Use dispatch_async or std::thread for anything involving file I/O or complex AI processing (like the RAG pipelines we ran).

What it costs, and when not to do it

This strict approach has a high development cost. Writing explicit specs takes 30% longer than throwing an any type at the problem.

When to skip this:

If you are building a CRUD app with low data frequency (e.g., a simple form entry).
If your app doesn't target low-end Android devices where JSI overhead is more pronounced.

When it is mandatory:

High-frequency data (health, finance, sensors).
Complex animations that must stay synced with native state.
When scaling a team. Without these guardrails, junior engineers will treat TurboModules like standard JS functions, eventually leading to a "death by a thousand cuts" performance profile that is nearly impossible to debug later.

At your level

Starting out

Stop using any in your TypeScript files immediately. TurboModule codegen relies on your types to build the C++ interface; if your types are vague, your native performance will be too. Focus on learning how TurboModuleRegistry differs from NativeModules.

Working engineer

Implement the telemetry wrapper mentioned in Step 3. You likely have modules that are slow, but you don't know which ones. Identify the top three slowest calls and refactor their specs to use primitives instead of objects.

Senior or staff

You own the architecture. Your job is to prevent the "jank" before it's written. Set up the CI/CD check to fail builds that use generic jsi::Object in TurboModule specs. This enforces a performance-first culture without you having to manually review every line of code.

Lead or director

Performance is a budget, not a feature. If your team is missing release deadlines due to "unexplained lag," it's likely a boundary issue. Allocate the 20% extra time needed for proper codegen specs now to avoid the 200% time cost of a performance refactor six months down the line.

In the interview

The Question: "How do TurboModules improve performance over the legacy Bridge?"

The Weak Answer: "They are faster because they use JSI instead of JSON serialisation, so there's less overhead when calling native code."

Why it's weak: It's a textbook answer. It doesn't show you've actually dealt with the consequences of JSI, such as thread blocking or memory management.

The Strong Answer: "TurboModules leverage JSI to provide synchronous access to native methods, eliminating the asynchronous JSON serialisation bottleneck. However, the real advantage is the type-safety provided by Codegen, which generates C++ structs. A strong implementation avoids jsi::Object in favour of primitives to minimize lookup overhead. The trade-off is that because it's synchronous, a poorly written native method can now block the JavaScript thread and drop frames, which wasn't as direct a risk with the asynchronous Bridge. You have to defend a 16ms frame budget by offloading heavy work to background threads and returning Promises."

The Senior/Staff Follow-up: "How do you handle large data transfers between JS and Native in the New Architecture?"
The "I've done this" Answer: "I wouldn't pass large blobs over JSI if I can avoid it. Even with TurboModules, moving a 10MB string is expensive. I’d prefer to pass a reference to a memory-mapped file or use ArrayBuffer / SharedArrayBuffer to share the memory space between the C++ layer and the JS engine. This avoids the copy-overhead entirely."

The hidden cost of TurboModules: Why Codegen is not a free lunch

Amit chakraborty — Thu, 08 Oct 2026 08:30:04 +0000

I was leading the architecture for a clinical AI platform at Synapsis Medical Technologies, where we were integrating real-time health data from wearables via Bluetooth Low Energy (BLE). We were hitting a wall with the legacy React Native bridge. High-frequency data packets—heart rate, SpO2, and accelerometer streams—were saturating the bridge, causing noticeable UI stutters and delaying the execution of our RAG-based clinical alerts.

To solve this, we migrated our native modules to the New Architecture (TurboModules) in React Native 0.7x. On paper, it was the perfect solution: synchronous execution, type safety, and no bridge congestion. Instead, our CI/CD pipeline, which I had previously optimized to a 4-hour release cycle, bloated by 25 minutes per build. We saw cryptic C++ compilation errors that stalled our 21-person engineering team for two days. The "type safety" we were promised required a rigid boilerplate that made simple feature additions a multi-file choreography across TypeScript, C++, and Java.

If you are moving to TurboModules because the documentation says it is "faster," you are only hearing half the story. The performance gains are real, but the tax on your developer experience and build infrastructure is significant.

Why the bottleneck moves from the Bridge to the Build

In the legacy architecture, the bridge was a JSON-based message bus. It was slow because every call had to be serialized, passed across the boundary, and deserialized. TurboModules eliminate this by using JSI (JavaScript Interface), allowing JavaScript to hold a direct reference to C++ host objects.

However, JSI requires C++ glue code to bind the JavaScript calls to the native platform code (Objective-C or Java). React Native uses a tool called codegen to generate this glue code.

The failure mode nobody warns you about is the Codegen-Build Loop. In the old way, you changed a Java file and re-ran the app. Now, if you change a single property in your TypeScript interface, codegen must re-run, generating new C++ headers, which then triggers a full recompilation of the native bridge layer. On a standard M2 MacBook Pro, this adds a non-trivial overhead to every native change. If your CI is running on resource-constrained runners, this is where your 4-hour release cycle starts to creep toward 5 hours.

The migration: A step-by-step hardening

Do not follow the "Hello World" tutorials that suggest moving your entire library at once. In my experience shipping 18+ production apps, the only way to survive this without breaking the build for the rest of your team is a staggered implementation.

1. Define the Spec strictly

Create a Native[ModuleName].ts file. The naming convention is not optional; codegen looks for the Native prefix.

// NativeHealthScanner.ts
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  // Use exact types. 'any' will fail codegen.
  readonly getSensorData: (sensorId: string) => Promise<string>;
  readonly startScan: (frequency: number) => void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('HealthScanner');

Why: codegen is a parser, not a compiler. If you use complex TypeScript unions or external type imports inside this file, the parser will crash with an unhelpful "Task :app:generateCodegenArtifactsFromSchema Failed" error. Keep this file isolated.

2. Trigger Codegen manually to verify

Before you try to compile the whole app, run the script to generate the specs.

# For iOS
cd ios && bundle exec pod install

Confirm it worked: Look into ios/build/generated/ios. You should see HealthScannerSpec.h and HealthScannerSpec-generated.mm. If these files aren't there, your package.json configuration for codegenConfig is likely pointing to the wrong directory.

3. Implement the C++ boilerplate (iOS)

This is where the "cost" becomes visible. You cannot just write Objective-C anymore. You must provide a bridge implementation that conforms to the generated C++ protocol.

// HealthScanner.mm
#import "HealthScanner.h"

@implementation HealthScanner
RCT_EXPORT_MODULE()

- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params
{
    return std::make_shared<facebook::react::NativeHealthScannerSpecJSI>(params);
}

// Your actual logic
- (void)startScan:(double)frequency {
    // Implementation
}
@end

The Trade-off: You are now maintaining a C++ shared pointer inside an Objective-C++ file. If your team consists purely of React developers, you have just increased the bus factor of your native infrastructure.

The hidden costs of the New Architecture

Having scaled a team from 0 to 21, I’ve seen how these architectural choices impact velocity.

Binary Size: TurboModules require the inclusion of the JSI and often the Hermes engine (though technically separate, they are designed to work together). In my experience, migrating a medium-sized app to full TurboModules and Fabric (the new renderer) can increase the initial APK size by 3MB to 5MB due to the C++ runtime requirements.
Compilation Time: As mentioned, our build times increased. Specifically, the ninja build process for C++ is CPU-intensive. If your developers are on 8GB RAM machines, they will feel the swap pressure during every native rebuild.
The "Sync" Trap: TurboModules allow synchronous calls to native. This is tempting for getting constants or simple state. However, if your native method takes more than 5ms (e.g., a quick disk read), you will drop frames on the UI thread because you’ve blocked the JS thread which is now coupled to the native execution.

At your level

Starting out

Do not start your project with TurboModules unless you have a specific performance requirement (like high-frequency data). Stick to the legacy bridge; it is better documented and has more StackOverflow coverage. Focus on learning how to pass data across the boundary before trying to optimize the boundary itself.

Working engineer

When you encounter a "Bridge Busy" warning in your logs, that is your signal to migrate that specific module only. You can run TurboModules and legacy modules side-by-side. Move your heaviest data-producers first—camera buffers, sensor streams, or large file processing.

Senior or staff

You own the build pipeline. Before enabling TurboModules, benchmark your CI. You may need to upgrade your GitHub Actions runners to macos-13-xlarge to offset the C++ compilation time. Establish a strict linting rule for Native[Module].ts files to prevent developers from importing complex types that break the codegen parser.

Lead or director

Understand that moving to the New Architecture is a hiring decision. You are moving away from "JavaScript developers who do a bit of mobile" toward "Systems engineers." Your team will need to be comfortable debugging C++ stack traces and understanding memory management in a hybrid environment.

In the interview

The Question: "Why would you choose TurboModules over the standard React Native bridge?"

The Weak Answer: "Because it's faster and it's the new way React Native works." This is weak because it ignores the implementation cost and assumes "new" equals "better."

The Strong Answer: A strong answer focuses on the JSI (JavaScript Interface). You should explain that TurboModules allow for synchronous execution and eliminate the JSON serialization overhead. You must mention the trade-off: the increased complexity of the codegen process and the requirement for C++ glue code.

The Senior-level Follow-up: "How does the migration affect your CI/CD and developer velocity?"
A candidate who has actually done this will talk about the increase in build times and the brittleness of the codegen parser. They will mention that while runtime performance improves, the feedback loop for native development slows down due to the re-compilation of generated C++ headers. They might also discuss the memory management implications of holding long-lived C++ objects via JSI versus the fire-and-forget nature of the legacy bridge.

The DevOps bootcamp · 2. The Linux you actually need

Amit chakraborty — Thu, 08 Oct 2026 04:30:08 +0000

The DevOps bootcamp · Chapter 2 of 14 · DevOps · new chapter every Thursday morning

By the end of this chapter: Work confidently with processes, files, permissions and networking.

The problem

Say you are a junior engineer on your first backend project. You need to test a branch on the team's shared staging server. You SSH in, pull your code, and run the start command. The terminal spits back Error: listen EADDRINUSE: address already in use :::8080.

You try changing the port, but the proxy routing traffic to your application expects 8080. You assume the previous version of the application is still running, but you do not know how to find it. You try running your new application as the superuser to force it through, and it starts, but immediately crashes with Permission denied: /var/log/staging-api/error.log.

Because you do not know how to ask Linux what is holding that port, or how to read the permissions on that file, you do the only thing you know: you reboot the staging server. It takes ten minutes to come back. When it does, your application works, but you have just taken down three other services your team was actively testing, costing four engineers an hour of lost work and earning a sharp message from your tech lead.

Before you start

You need a Linux environment. Ubuntu 24.04 LTS is the current standard for server deployments. You can use Windows Subsystem for Linux (WSL2), a local virtual machine, or a cloud instance.

Verify your environment by checking the operating system release:

cat /etc/os-release

The output must include PRETTY_NAME="Ubuntu 24.04 LTS".

Verify you have standard utilities installed:

python3 --version

The output should be Python 3.12.x.

How do you find what is holding a port?

When an application claims a network port, the Linux kernel prevents any other process from claiming it. If a deployment script fails, if an application crashes poorly, or if a process is sent to the background and forgotten, the process remains alive and the port remains locked.

You cannot ask the port to release the process. You must ask the kernel which process ID (PID) owns the port, and then terminate that PID.

The tool for querying network sockets is ss (socket statistics). By asking it to list listening TCP ports and the processes attached to them, you get the exact PID blocking your deployment. You must run this command as the superuser (sudo); if you run it as a standard user, the kernel will hide the PIDs of processes owned by other users, leaving the process column blank and you guessing.

Once you have the PID, you use the kill command. Despite the name, kill does not kill processes; it sends signals to them. A standard kill <PID> sends SIGTERM (signal 15), which politely asks the application to shut down. A well-written application will catch this, finish writing its logs, release its port, and exit. A hung application will ignore it. When that happens, you use kill -9 <PID>, which sends SIGKILL. This signal goes directly to the kernel, which instantly destroys the process without giving the application a chance to react.

Why does root own the log file?

Linux treats almost everything as a file, and every file has an owner, a group, and a strict set of permissions. Permissions are divided into read (r), write (w), and execute (x). They are applied to three categories: the user who owns the file, the group assigned to the file, and everyone else.

When you run an application with sudo, it executes as root (user ID 0). Any file it creates is owned by root. If you realise your mistake and later try to run that same application as a standard user, the application will attempt to append to its existing log file, discover it does not have write permissions to a root-owned file, and crash.

You view these permissions using ls -l. The output begins with a ten-character string, such as -rw-r--r--.

The first character is the type (- for a file, d for a directory).
The next three are the owner's permissions (rw- means read and write, but not execute).
The next three are the group's permissions (r-- means read only).
The final three are everyone else's permissions (r-- means read only).

You change who owns a file with chown (change owner). You change the permissions themselves with chmod (change mode). While you can use letters to change permissions, engineers use octal numbers because they are exact and overwrite the previous state entirely. Read is worth 4, write is worth 2, and execute is worth 1. You add them together for each category.

A permission of 755 means the owner gets 7 (4+2+1: read, write, execute), the group gets 5 (4+1: read, execute), and everyone else gets 5. A permission of 644 means the owner gets 6 (4+2: read, write), and everyone else gets 4 (read only).

Build it

We will recreate the staging server failure on your machine, diagnose the port collision, kill the ghost process, and fix the resulting permission trap.

Step 1: Create the ghost process
Start a dummy web server in the background, bound to port 8080. The & at the end tells the shell to run this in the background, returning control of the terminal to you.

python3 -m http.server 8080 > /dev/null 2>&1 &

Why: This simulates the previous version of your application that failed to shut down.
How to confirm: Run curl http://localhost:8080. It will output a directory listing of your current folder.

Step 2: Identify the blockage
Query the kernel for all listening TCP ports and the processes holding them.

sudo ss -lptn | grep :8080

Why: l shows listening sockets, p shows processes, t shows TCP only, and n forces numeric output (preventing Linux from trying to resolve 8080 to a service name, which is slow). We pipe (|) the output to grep to filter for our specific port.
How to confirm: You will see output resembling:
LISTEN 0 5 0.0.0.0:8080 0.0.0.0:* users:(("python3",pid=14235,fd=3))
The number after pid= (in this case, 14235) is what you need.

Step 3: Terminate the ghost process
Send a kill signal to the PID you found in Step 2. Replace 14235 with your actual PID.

kill -9 14235

Why: We use -9 to force the kernel to destroy the process immediately, simulating clearing a hung application.
How to confirm: Run sudo ss -lptn | grep :8080 again. The output will be completely empty. The port is free.

Step 4: Create the permissions trap
Create a log directory and file as the root user.

sudo mkdir -p /var/log/staging-api
sudo touch /var/log/staging-api/error.log

Why: This simulates the moment you tried to force your application to start using sudo, leaving behind root-owned state.
How to confirm: Run ls -l /var/log/staging-api/error.log. The output will show root root as the owner and group.

Step 5: Trigger the failure
Attempt to write to the log file as your standard user.

echo "Starting application..." >> /var/log/staging-api/error.log

Why: This simulates your application trying to start up and write its first log line.
How to confirm: The terminal will output exactly: bash: /var/log/staging-api/error.log: Permission denied.

Step 6: Fix the ownership and run successfully
Change the ownership of the directory and its contents to your current user. $USER is an environment variable containing your username.

sudo chown -R $USER:$USER /var/log/staging-api

Why: The -R flag applies the change recursively to the directory and everything inside it. The $USER:$USER syntax sets both the owner and the group to your user.
How to confirm: Run the application write command again:

echo "Starting application..." >> /var/log/staging-api/error.log
cat /var/log/staging-api/error.log

The output will successfully print Starting application.... You have cleared the port, fixed the permissions, and started the service without rebooting the machine.

When this breaks

Symptom: ss: command not found
Cause: You are running a minimal Linux distribution, often inside a container, that has stripped out network utilities to save space.
Fix: Install the package that provides ss. On Ubuntu/Debian, run sudo apt-get update && sudo apt-get install iproute2.

Symptom: kill -9 returns silently, but the process still appears in ss or ps.
Cause: The process is a zombie (listed as Z state in ps) or in uninterruptible sleep (listed as D state). A zombie is already dead, but its parent process has not acknowledged its death. Uninterruptible sleep means the process is waiting on hardware, like a hung network drive, and the kernel will not deliver the kill signal until the hardware responds.
Fix: For a zombie, you must find and kill its parent. Find the parent PID (PPID) with ps -o ppid= -p <PID>, then kill the parent. For a process in uninterruptible sleep waiting on dead hardware, you cannot kill it. You must reboot the machine.

Symptom: bash: /var/log/staging-api/error.log: Permission denied even when you run sudo echo "test" >> /var/log/staging-api/error.log.
Cause: The shell parses the command line before executing it. It sees the redirect (>>) and attempts to open the file using your standard user permissions before it runs sudo echo. The sudo only applies to the echo command, not the file redirection.
Fix: Pass the string to the tee command, running tee as root.
echo "test" | sudo tee -a /var/log/staging-api/error.log

What it costs

Manual Linux administration is imperative: you are issuing commands that change the state of the machine. The cost of this approach is configuration drift.

If you fix a permissions error on a staging server by running chown, you have fixed it once, on one machine. The next time the server is rebuilt, or when you attempt to deploy to production, the error will return. The server's true configuration now exists only in the command history of your terminal, not in source control.

This commits you to remembering what you typed. It scales poorly, guarantees failures during high-stress deployments, and turns servers into fragile pets that engineers are afraid to replace. We learn these commands so we can diagnose failures and understand what the operating system requires, but we do not use them to deploy software.

In the interview

A standard infrastructure interview question is: "You are deploying a new version of a backend service to a Linux machine, and it fails to start. Walk me through how you debug it."

A weak answer is: "I would check the application logs, and if that doesn't work, I would restart the server." This is weak because it assumes the application lived long enough to write logs (which it cannot do if the port is blocked or the log directory is restricted), and it treats restarting a production server as a valid diagnostic step.

A strong answer names the specific sequence of investigation. You check process status with ps or systemctl, check port bindings with ss -lptn, check file permissions with ls -la, and read the application's standard error output directly.

The follow-up questions will change based on the level you are interviewing for. A junior candidate is expected to know the commands (ss, kill, chmod) and what they do. A senior candidate is expected to explain the lifecycle: why the old version did not release the port (perhaps the deployment script failed to send a SIGTERM, or the application does not handle signals gracefully) and why the permissions are wrong. An engineering manager or staff-level loop will probe the systemic failure: why is a human SSHing into a machine to deploy in the first place, and how do we move this process to an automated, immutable pipeline?

Your tasks

Find the SSH daemon. Find the PID of the process listening on port 22. Done looks like: You have a number. Running ps -p <number> outputs a line ending in sshd.
Create a read-only secret. Create a file named secret.txt. Change its permissions so that only your user can read it, and absolutely nobody (including you) can write to it or execute it. Done looks like: Running ls -l secret.txt shows -r--------. Running echo "test" > secret.txt fails with Permission denied.
Hunt a disconnected process. Start a background process by running sleep 3600 &. Close your terminal completely to log out of the shell. Open a new terminal, log back in, find that specific sleep process, and kill it. Done looks like: Running ps aux | grep sleep shows nothing after you have killed it.

Your tasks this week

Do the exercises above before the next chapter. Reading a tutorial and doing
one are different activities and only one of them changes what you can build.

The DevOps bootcamp

Chapter 2 of 14. New chapter every Thursday morning.
Next: The shell: pipes, scripts and automating your own machine.

Written by Amit Chakraborty — founding engineer and senior architect: React Native, AI and RAG systems, production architecture. Portfolio · LinkedIn · GitHub.

Need this built, reviewed or taught to your team? Get in touch or email amit@devamit.co.in. Available for senior and founding engineering roles, consulting and training, remote worldwide.

The Silent Deadlock: Debugging Fabric Renderer Stalls in Production

Amit chakraborty — Thu, 08 Oct 2026 04:30:03 +0000

I was serving as the founding engineer at a HealthTech AI platform, Synapsis Medical Technologies, where we were managing a stack that integrated real-time wearable data with a HIPAA-aligned RAG pipeline. We had just migrated our core mobile interface to React Native 0.76 to leverage the New Architecture. On paper, the Fabric renderer promised synchronous layout and better interop with our native C++ modules.

Then the clinical feedback started hitting my desk.

Physicians using the app reported that the UI would "freeze" for three to five seconds when opening a patient’s longitudinal record—a view heavy with complex SVG charts and streaming LLM responses. Our crash reporting (Sentry) showed zero crashes. Our JavaScript thread was idle. But the screen was unresponsive to touch. We were losing clinical trust, and in a health-tech environment, a five-second UI stall isn't just a bug; it's a failure of the tool.

I spent 72 hours tracing this to the way Fabric handles the "Shadow Tree" during high-frequency state updates. This is the reality of the New Architecture: you trade the asynchronous bridge bottleneck for a synchronous thread-locking problem that is significantly harder to debug.

Why Fabric Stalls Under Load

In the old architecture, the Yoga layout engine ran on a background "shadow thread." If the layout took too long, the UI thread remained free to scroll or show a loading spinner. In the Fabric renderer, the layout calculation can be triggered synchronously on the UI thread to prevent the "white flash" of unstyled content.

The failure happens when you combine three factors:

High-frequency updates: A streaming LLM response or a 60Hz wearable data feed.
Deep Component Trees: A complex FHIR-compliant medical record with nested lists.
Synchronous Triggers: Using useLayoutEffect or certain native gestures that force Fabric to commit a new Shadow Tree immediately.

When these collide, the UI thread enters a state of "Commit Contention." The C++ Shadow Tree is being mutated so rapidly that the UI thread spends its entire budget calculating layout, leaving no time to process the touch events sitting in the queue. Because the JS thread is actually finished with its work, your standard performance monitors will tell you the app is healthy.

Detecting and Fixing Shadow Tree Contention

You cannot fix this by optimizing JavaScript. You have to change how the renderer commits changes to the native side.

1. Identify the "Ghost Stall"

First, confirm it is a Fabric stall and not a JS event loop block. Run the app with the Perf Monitor visible. If the JS FPS is 60 but the UI FPS drops to 0-5 during an interaction, you are looking at a Fabric commit bottleneck.

2. Batching with `useTransition`

In React Native 0.76+, you must stop treating all state updates as equal. For our clinical AI stream, I moved the text updates into a transition. This tells Fabric that the update is low priority and can be interrupted by a touch event.

import { useState, useTransition } from 'react';

function PatientRecord({ stream }) {
  const [data, setData] = useState('');
  const [isPending, startTransition] = useTransition();

  // WRONG: This forces a synchronous Fabric commit on every chunk
  // onChunk(chunk => setData(prev => prev + chunk));

  // RIGHT: This allows Fabric to prioritize UI responsiveness over the text update
  onChunk(chunk => {
    startTransition(() => {
      setData(prev => prev + chunk);
    });
  });
}

3. Audit Native Component Synchronicity

If you use react-native-svg or custom Fabric components, check if they are calling invalidate on the main thread too frequently. In our case, the wearable heart-rate graph was forcing a layout pass on every data point.

To confirm this, I used the ETW (Event Tracing for Windows) equivalent on iOS: Instruments (System Trace). Look for common_mount and layout calls. If you see a wall of [Fabric] commit blocks longer than 16ms, you must wrap the data source in a throttle.

4. Implement a "Commit Guard"

In my experience shipping 18+ production apps, the most effective way to handle this under load is to decouple the data frequency from the render frequency. Even with Fabric, the human eye cannot perceive updates faster than 30-60fps.

// A simple throttle for high-frequency clinical data
useEffect(() => {
  const interval = setInterval(() => {
    if (buffer.current.length > 0) {
      setRenderData(buffer.current);
      buffer.current = [];
    }
  }, 32); // Target ~30fps for heavy UI updates
  return () => clearInterval(interval);
}, []);

The Cost of the New Architecture

Migrating to Fabric is not a free performance upgrade. In our CI/CD overhaul where I cut release cycles from 2 days to 4 hours, we had to add specific automated "jank tests" because Fabric failures are silent.

The Trade-off:

Memory: Fabric keeps the Shadow Tree in C++. While this is faster, I observed a ~15-20% increase in baseline memory usage for complex views compared to the old architecture.
Initialization: The "New Architecture" has a heavier startup cost. On low-end Android devices, we saw the onCreate to onContentAppear time increase by roughly 200ms because of the C++ TurboModule initialization.

Do not enable the New Architecture if your app is a simple CRUD tool with flat lists. The complexity of debugging the C++ layer outweighs the benefits unless you are doing high-frequency data visualization or complex animations that require synchronous layout.

At Your Level

Starting out

Stop using useLayoutEffect unless you specifically need to measure a DOM/Shadow node before the user sees it. In Fabric, this hook is a common source of UI-blocking stalls. Stick to useEffect to keep the UI thread free.

Working engineer

Learn to use the React DevTools Profiler specifically to look for "Commit" times. If your "Commit" phase is consistently over 10ms, your component tree is too deep for Fabric to handle efficiently. Flatten your hierarchy—use Fragment instead of View where possible.

Senior or staff

You own the architecture. You must implement a strategy for "Concurrent Metadata." This means deciding which data streams (like our AI RAG pipeline) are allowed to block the UI and which must be deferred. Establish a lint rule or a wrapper around setState for high-frequency events.

Lead or director

Understand that moving to the New Architecture increases your "debugging tax." You will need engineers who understand the C++ lifecycle of React Native, not just React. Budget time for a comprehensive regression of your most complex screens, as the performance characteristics will flip—what was fast might become slow due to lock contention.

In the Interview

The Question: "How does the Fabric renderer improve performance over the old architecture, and what are the risks?"

The Weak Answer: "It uses a C++ core and removes the bridge, making everything faster and smoother." This is a marketing answer that ignores the implementation reality.

The Strong Answer: A senior candidate will discuss synchronous layout capabilities and the removal of the three-tree problem (JS, Shadow, and Native trees). They should name the specific trade-off: while it eliminates the "async jump" (where the UI and JS threads are out of sync), it introduces the risk of UI thread starvation. If the JS thread pushes too many synchronous commits, the UI thread cannot process gestures, leading to a "frozen" app that hasn't actually crashed.

The Follow-up: "How do you debug a UI freeze where the JS thread is idle?"
The candidate should mention using System Trace (Instruments) or systrace to look for C++ mutex contention or long Mounting phases in the Fabric renderer. If they only mention console.log or the JS profiler, they haven't lived with the New Architecture under load.

FastAPI in production · 1. FastAPI in one hour

Amit chakraborty — Wed, 07 Oct 2026 16:30:07 +0000

FastAPI in production · Chapter 1 of 12 · Backend · new chapter every Wednesday night

By the end of this chapter: Get a typed, documented API running and understand what generated the documentation.

The problem

Say you are an engineer tasked with standing up a new user-preferences service. The frontend team needs it by Friday. You write a quick Flask app, define a /preferences endpoint, and write up a wiki page explaining that the endpoint expects a JSON payload with a user_id (an integer) and a theme (a string).

On Thursday afternoon, the frontend team deploys to staging. The service immediately starts throwing 500 Internal Server Errors. You check the logs and see a TypeError. The frontend sent {"user_id": "12345", "theme": "dark"}. Because user_id came in as a string, your database query failed. You patch the code to cast the ID to an integer, deploy the hotfix, and tell the frontend team to try again. Ten minutes later, they complain that the API is returning a 200 OK, but the response shape does not match the wiki page you wrote. The wiki is out of date, the validation is manual, and you are spending your afternoon acting as a human type-checker.

This is the exact failure mode FastAPI was built to eliminate. It ties the shape of your data, the validation of incoming requests, and the documentation of your API to a single source of truth: Python type hints.

Before you start

You need Python 3.10 or newer. We will use FastAPI 0.112.2, which introduced the [standard] extra to bundle the framework with its recommended server, Uvicorn.

Create a new directory, set up a virtual environment, and install the package:

python -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]==0.112.2"

Verify the installation by checking the version in your terminal:

python -c "import fastapi; print(fastapi.__version__)"

This must output 0.112.2 before you continue.

Why documentation drifts from code

In a traditional Python web framework, the code that handles a request and the documentation that describes it are entirely separate. You write a function that accepts a request object, you parse the JSON body, and you write a docstring or a separate YAML file detailing what that JSON should look like.

When a requirement changes—say, theme becomes an optional field—you must update the parsing logic, the validation logic, and the documentation. If you forget one, the system degrades. The documentation lies to the client, or the validation fails to protect the database.

FastAPI prevents this by generating an OpenAPI schema directly from your function signatures. OpenAPI is a language-agnostic specification for describing REST APIs. Because FastAPI reads the type hints on your Python functions at startup, the generated OpenAPI schema is always an exact reflection of the code that will execute. If you change a type hint from str to int, the documentation updates automatically, and the framework immediately begins rejecting requests that cannot be parsed as integers.

The role of Pydantic

FastAPI does not do the validation itself. It delegates data parsing and validation to Pydantic, a library that enforces type hints at runtime.

When a request arrives, FastAPI inspects the signature of your route function. If it sees a Pydantic model in the signature, it takes the incoming JSON payload, passes it to Pydantic, and attempts to construct that model. If the payload is valid, your function receives a fully instantiated Python object. If the payload is invalid, Pydantic raises an error, which FastAPI catches and translates into a 422 Unprocessable Entity HTTP response. Your route function never even executes.

This means you can write your business logic under the assumption that the data is perfectly formed. You do not need to check if a field is missing, or if a string was passed instead of an integer. If the code inside your route function is running, the contract was met.

Build it

We will build a single-file API that accepts user preferences, validates them, and returns a structured response.

Step 1: Define the data contract
Create a file named main.py. Import FastAPI and Pydantic, and define the shape of the data you expect the client to send.

from fastapi import FastAPI
from pydantic import BaseModel

class UserPreferences(BaseModel):
    user_id: int
    theme: str
    notifications_enabled: bool = True

Why: Inheriting from BaseModel tells Pydantic to treat this class as a data validator. user_id and theme are required. notifications_enabled is optional and defaults to True.

Step 2: Initialize the application
Add the FastAPI application instance to main.py.

app = FastAPI(
    title="Preferences API",
    version="1.0.0"
)

Why: This app object is the ASGI (Asynchronous Server Gateway Interface) application. The server will look for this exact variable to route incoming network traffic.

Step 3: Write the route
Create an endpoint that accepts a POST request. Use the Pydantic model as a parameter.

@app.post("/preferences")
def update_preferences(prefs: UserPreferences):
    # If we reach this line, 'prefs' is guaranteed to be a valid UserPreferences object.
    return {
        "message": "Preferences updated successfully",
        "data": prefs
    }

Why: The @app.post decorator tells FastAPI to route HTTP POST requests for /preferences to this function. By typing the prefs argument as UserPreferences, you instruct FastAPI to read the request body, validate it against the model, and pass the result to your function.

Step 4: Run the server
Start the application using the FastAPI CLI (which wraps Uvicorn). Run this command in your terminal:

fastapi dev main.py

Why: The dev command starts a local server on port 8000 and watches your files for changes, reloading the server automatically.
How to confirm: You should see output ending with Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit).

Step 5: Test the validation
Open a second terminal and send a valid request using curl:

curl -X POST http://127.0.0.1:8000/preferences \
  -H "Content-Type: application/json" \
  -d '{"user_id": 42, "theme": "dark"}'

Expected output:

{"message":"Preferences updated successfully","data":{"user_id":42,"theme":"dark","notifications_enabled":true}}

Notice that notifications_enabled was automatically injected with its default value.

Step 6: Inspect the generated documentation
Open your web browser and navigate to http://127.0.0.1:8000/docs.
Why: FastAPI has generated an interactive Swagger UI based on your code. You will see the /preferences endpoint. If you click into it and look at the "Schema" section, you will see the exact JSON structure required, including the types and default values. You did not write this documentation; it was compiled from your Python type hints.

When this breaks

The 422 Unprocessable Entity
Symptom: The client sends a request and receives a 422 HTTP status code, and your route function never executes.
Cause: The incoming data violated the Pydantic contract. For example, sending "theme": ["dark"] (a list instead of a string).
Fix: Read the JSON body of the 422 response. FastAPI provides an exact path to the failure.

{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "theme"],
      "msg": "Input should be a valid string",
      "input": ["dark"]
    }
  ]
}

The client must fix their payload to match the schema.

Blocking the event loop
Symptom: Under load, the API suddenly becomes unresponsive. Requests queue up and time out.
Cause: You defined a route with async def but performed a synchronous, blocking operation inside it (like a time.sleep(), a synchronous database call, or a heavy CPU calculation).

@app.get("/slow")
async def slow_route():
    time.sleep(5) # This blocks the entire server
    return {"status": "done"}

FastAPI runs on a single-threaded event loop. If an async def function blocks, it prevents the server from handling any other requests.
Fix: If you are using synchronous libraries, define your route with a standard def instead of async def. FastAPI will automatically run standard def functions in a separate threadpool, keeping the main event loop free to accept new requests.

Address already in use
Symptom: When running fastapi dev main.py, the terminal outputs [Errno 98] Address already in use or [Errno 48] Address already in use.
Cause: Another process (often a previous instance of your FastAPI app that did not shut down cleanly) is already listening on port 8000.
Fix: Find the process using the port and kill it. On Linux or macOS: lsof -i :8000, then kill -9 <PID>. Alternatively, start FastAPI on a different port: fastapi dev main.py --port 8080.

What it costs

The primary cost of FastAPI's approach is strictness. In a Flask app, if you want to accept an arbitrary, deeply nested JSON blob and just store it in a database without inspecting it, you simply call request.get_json() and pass the resulting dictionary along.

In FastAPI, to get the documentation and validation benefits, you must define the exact shape of that blob using Pydantic models. If the upstream service sending you data frequently adds random fields, and you use a strict Pydantic model, those requests will either be rejected or the extra fields will be silently stripped out, depending on your configuration.

Furthermore, Pydantic validation is not free. While Pydantic V2 (written in Rust) is exceptionally fast, parsing and validating a large JSON payload into Python objects takes more CPU cycles than Python's native json.loads(). For 99% of web applications, this overhead is invisible. But if you are building a high-throughput ingestion pipeline processing tens of thousands of large payloads per second, the validation step will become a bottleneck.

Finally, you are buying into an ecosystem. Your business logic becomes tightly coupled to Pydantic models and FastAPI's dependency injection system. Migrating a complex FastAPI codebase to another framework later requires significant rewriting, as the framework's concepts bleed deeply into your route handlers.

In the interview

When interviewing for a backend role, a common question is: "Why would you choose FastAPI over Flask or Django for a new microservice?"

A weak answer focuses purely on speed: "FastAPI is faster because it is asynchronous." This is weak because raw framework speed rarely dictates the performance of a real-world application; database queries and network calls do. Furthermore, it shows a surface-level understanding of the tool's actual value proposition.

A strong answer centers on developer velocity and contract enforcement. "I would choose FastAPI because it eliminates the drift between the API implementation and its documentation. By using Pydantic models as type hints, the framework guarantees that my route handlers only execute if the incoming payload strictly matches the contract. This prevents an entire class of type-casting bugs and offloads manual validation boilerplate."

If you are a junior candidate, the interviewer expects you to explain how the OpenAPI docs are generated and how a 422 error is produced. If you are a senior candidate, the interviewer will likely probe the trade-offs: they will ask you when you would not use async def for a route, or how you handle sharing Pydantic models across different services without creating a distributed monolith. An engineering manager will want to hear about onboarding: how the auto-generated Swagger UI allows frontend teams to unblock themselves without waiting for backend engineers to write documentation.

Your tasks

Add a GET endpoint with a query parameter.
Create an endpoint at @app.get("/users"). Have it accept an integer query parameter called limit with a default value of 10. Return a JSON object echoing the limit. Open the /docs UI and verify that limit appears as a query parameter, not a request body.
Done when: curl "http://127.0.0.1:8000/users?limit=5" returns {"limit": 5}.
Trigger a validation failure.
Using the POST /preferences endpoint from the chapter, send a curl request where the user_id is a string that cannot be cast to an integer (e.g., "user_id": "abc").
Done when: You receive a 422 status code and can identify the exact loc (location) in the JSON response that points to user_id.
Nest a Pydantic model.
Create a new Pydantic model called Address containing a city (string) and country (string). Update the UserPreferences model to include an address field typed as Address.
Done when: You can successfully send a POST request with a nested JSON object for the address, and the /docs UI correctly displays the nested schema.

Your tasks this week

Do the exercises above before the next chapter. Reading a tutorial and doing
one are different activities and only one of them changes what you can build.

FastAPI in production

Chapter 1 of 12. New chapter every Wednesday night.
Next: Pydantic as your API contract.

Written by Amit Chakraborty — founding engineer and senior architect: React Native, AI and RAG systems, production architecture. Portfolio · LinkedIn · GitHub.

Need this built, reviewed or taught to your team? Get in touch or email amit@devamit.co.in. Available for senior and founding engineering roles, consulting and training, remote worldwide.

The Hidden Performance Ceiling of React Native Skia in Production

Amit chakraborty — Wed, 07 Oct 2026 16:30:02 +0000

I was three weeks out from a major release for a clinical HealthTech platform when we hit a wall that didn't exist in our staging environment. We were using react-native-skia to render real-time physiological waveforms—ECG and SpO2 data—streaming from wearable devices. On an iPhone 15 Pro, the 60 FPS animations were fluid. On the mid-range Android tablets used in the clinics, the UI thread stayed responsive, but the Skia drawing layer began to lag three seconds behind the actual data stream.

The symptom wasn't a crash or a Redbox error. It was "frame accumulation." Because Skia runs on the JavaScript thread by default (or the UI thread depending on your configuration), high-frequency updates to a SkiaView can saturate the bridge or the JSI, leading to a mounting execution queue. We lost three days of development trying to reconcile why the same code that passed automated performance tests failed when subjected to the sustained, 24-hour data streams required for clinical monitoring.

In my experience shipping 18 production applications, Skia is often touted as the "Flutter-like" saviour for React Native performance. The reality is that it introduces a new category of failure modes—specifically memory leaks in the C++ layer and drawing cache invalidation storms—that you won't see in a "Hello World" or a basic chart demo.

Why the "Drawing Loop" Fails Under Load

Most developers treat Canvas like a standard React component. If the props change, the component re-renders. However, react-native-skia uses the JSI (JavaScript Interface) to host C++ objects. When you pass a large array of points to a Path object 60 times a second, you aren't just changing a pointer; you are asking the Skia engine to re-tessellate geometry.

The failure happens because of the Asynchronous Mismatch. Even with the New Architecture (TurboModules and Fabric) in React Native 0.76, the bridge between the JS logic calculating the path and the GPU executing the draw call has a finite throughput. If your calculation takes 12ms and your draw takes 6ms, you’ve already exceeded the 16.6ms window for 60 FPS. Unlike standard View components, Skia won't just "drop" the frame; it will often attempt to process the backlog, leading to the "rubber-banding" effect where animations speed up unnaturally to catch up to the current state.

The Fix: Step-by-Step Production Hardening

To move from a prototype to a production-grade Skia implementation that survives sustained load, follow these steps.

1. Externalise the Value State

Do not use useState for high-frequency Skia data. React’s reconciliation is too slow for 60Hz drawing. Use useSharedValue from react-native-reanimated, which Skia supports natively.

The Action: Replace your data arrays with SkiaMutableValue or Reanimated Shared Values.
Why: This keeps the data updates entirely on the UI/Worklet thread, bypassing the JS thread’s event loop.
How to confirm: Open the Flipper Performance Monitor. The "JS" thread usage should remain flat even as the animation runs.

2. Manual Path Management and Point Capping

A common mistake is passing a raw array of 1,000+ points to a Skia Path. In a production environment, especially on Android devices with Mali GPUs, this causes the GPU driver to hang.

The Action: Implement a point-decimation algorithm (like Douglas-Peucker) or a simple radial distance filter before the data hits the path.

// Example of a simple distance-based decimation
const simplifiedPoints = points.filter((p, i) => {
  if (i === 0) return true;
  const prev = points[i-1];
  return Math.abs(p.x - prev.x) > 0.5 || Math.abs(p.y - prev.y) > 0.5;
});

Confirm it worked: Monitor the GPU usage in Xcode Instruments. You should see a stable memory footprint rather than a "sawtooth" pattern.

3. Dispose of Skia Objects Manually

Skia objects like SkImage, SkTypeface, and SkRuntimeEffect are C++ wrappers. While the JS garbage collector (GC) eventually cleans them up, it is not aware of the memory pressure on the C++ side. In the HIPAA-aligned systems I’ve architected, unmanaged Skia objects led to OOM (Out of Memory) crashes after 40 minutes of continuous use.

The Action: Use the useImage or useFont hooks provided by the library, but for custom shaders or paths created inside a useMemo, you must use the .delete() or .dispose() methods if they are available in your version, or ensure they are wrapped in useRawValue.

4. Offscreen Composition

If you have static elements (like a grid or background) and dynamic elements (the waveform), do not redraw the static elements every frame.

The Action: Use a Picture or Image snapshot for the static background.
Why: SkPicture records drawing commands and plays them back without re-calculating the geometry. I have seen this reduce GPU load by 30-40% in complex dashboard UIs.

What it Costs and When to Avoid It

The trade-off for this performance is architectural complexity. Once you move to useSharedValue and manual path management, you lose the "declarative" simplicity of React. You are essentially writing C++ logic in a JavaScript syntax.

Do not use Skia if:

Accessibility is a priority: Skia draws to a canvas. The elements inside the Canvas are invisible to Screen Readers (VoiceOver/TalkBack) unless you manually build a parallel "shadow" tree of accessible views.
Text Heavy UIs: Skia's text rendering (especially with SkParagraph) requires manual font management and lacks the sophisticated hyphenation and RTL support built into the native iOS/Android Text components.
Simple Layouts: If you can achieve the design with View and CSS, do it. The overhead of bringing the Skia engine into your binary (adding ~4-8MB to the APK size) is not worth it for rounded corners or simple shadows.

At Your Level

Starting Out

Focus on the difference between the "JS Thread" and the "UI Thread." Your first goal is to get a Skia animation running without the JS thread dropping below 58 FPS. Use react-native-reanimated for all Skia transforms immediately; do not learn the "wrong" way first.

Working Engineer

Profile your app on a low-end Android device (e.g., a Samsung A-series). If you see "jank" or stuttering, look at your Path objects. Are you recreating the path string or the path object on every render? Move all path construction into a useDerivedValue to keep it off the React render cycle.

Senior or Staff

You own the memory lifecycle. You must establish patterns for "Snapshotting"—capturing complex static vector groups as bitmapped images to save draw calls. You should also be looking at SkiaRuntimeEffects (shaders) to offload heavy visual processing from the CPU to the GPU.

Lead or Director

Understand the binary size vs. UX trade-off. Adding Skia is a long-term commitment to a specific rendering engine. Ensure your team has the capacity to handle the "Accessibility Gap" created by Canvas-based rendering, as this often requires 20% more effort in the QA phase to meet compliance standards like WCAG.

In the Interview

The Question: "We're seeing significant frame drops when rendering a real-time chart with React Native Skia. How do you diagnose and fix this?"

The Weak Answer: "I would use useMemo to memoize the data and make sure I'm not doing too many re-renders. I might also try to reduce the number of points in the chart." This is weak because it assumes the bottleneck is React's reconciliation, whereas the bottleneck in Skia is usually the JSI bridge or GPU tessellation.

The Strong Answer: A strong candidate will identify the Thread Boundary. They will discuss moving the data stream into a SharedValue to stay on the UI thread and avoid the bridge. They will mention GPU Overdraw—the cost of drawing pixels that are later covered by other pixels—and how to use SkPicture to cache static layers. They should also mention the Garbage Collection lag between JS and C++, and how sustained high-frequency updates can lead to memory pressure that the JS GC doesn't respond to quickly enough.

The Senior/Staff Follow-up: "How does Skia's rendering impact the main thread's ability to handle user interactions like scrolling?"
The answer should touch on the fact that if Skia is configured to run on the UI thread, a heavy draw call can block touch events. A senior engineer will suggest offloading complex path calculations to a Web Worker-like pattern or a background thread via a TurboModule, then passing the final result to the UI thread only for the final draw.