Lesson 18 left off with a specific, uncomfortable fact: every call across the legacy bridge pays a JSON serialization cost on both ends, whether the payload is one boolean or a large object, and that cost scales with how often you cross. A TurboModule is the New Architecture's answer — a native module built on JSI instead of the legacy bridge, where JavaScript holds a direct reference to a native C++ object (a `HostObject`) and calls into it the way it would call any other JavaScript object's method, with no message queue and no JSON round-trip in between.
What makes a TurboModule genuinely different to build, not just to use, is codegen: instead of hand-writing the glue between a JavaScript-shaped interface and native Swift/Kotlin code, you write one TypeScript spec file describing the module's shape, and a build-time code generator reads that spec and produces the native interface code — protocol conformances on iOS, abstract base classes on Android — that your platform implementation then fills in. Get the spec wrong or skip a required piece, and codegen either fails the build outright or produces an interface your implementation cannot compile against, which is a stricter, earlier-failing contract than the legacy bridge ever enforced.
This lesson builds one TurboModule from spec to registration on both platforms, tracing the exact flow: TypeScript spec, codegen output, Kotlin implementation, Swift implementation, and how JavaScript ends up calling into either one without ever knowing which platform it's running on. The payoff is not just speed — it's that the interface is now type-checked at build time on both sides, catching a whole class of mismatch bugs the legacy bridge could only ever surface at runtime.
Analogy🏏Cricket
🏏 Think of it like cricket: A stadium curator preparing a pitch for a Test match does not improvise the specifications on the day — there is a written, agreed document specifying exact grass length, exact soil composition, exact moisture targets, submitted to the match referee well before the game, and the referee's inspection checks the actual pitch against that document line by line. If the document said one thing and the groundstaff delivered another, the mismatch is caught at inspection, before a ball is bowled, not discovered mid-match when a delivery behaves unexpectedly. This is a fundamentally different discipline from a groundstaff simply doing their best and hoping the pitch plays fairly on the day — the written specification is what lets an independent inspection verify correctness before the stakes are live. A TurboModule's TypeScript spec file is that written specification: it says exactly what methods exist, what types they take and return, before either the Swift or Kotlin implementation is written. Just as the referee's inspection checks the actual pitch against the submitted document and stops the match from starting on a mismatch, codegen checks the actual native implementation against the spec at build time and fails the build on a mismatch, rather than letting the app ship and fail on the field. The insight is that writing the contract down first, separately from the implementation, is what makes independent verification against that contract possible at all — a pitch inspected against a real document catches problems a purely trust-based process never could.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.