Codegen for TurboModules: Generating Type-Safe Interfaces

1. Why manual bridging was error-prone

In the old architecture, every native module was manually rebuilt with matching method signatures on iOS and Android, while JavaScript discovered which methods even existed at runtime purely through reflection or string-based lookup. A misspelled method, a forgotten parameter, or a type mismatch between the JavaScript and native implementation often only surfaced as a runtime error, sometimes only on a rarely hit code path in production.

Since both platforms were maintained independently, the iOS and Android implementation of a module frequently drifted apart over time, for example when a new parameter was only added on one platform. Codegen addresses exactly this: a single, typed spec file becomes the one source of truth from which both platforms are generated consistently.

2. How codegen works: from TypeScript spec to generated code

Codegen reads special TypeScript files at build time, recognized by convention as NativeXyz.ts, that export an interface extending TurboModule. A parser first turns this interface into a platform-independent schema representation as JSON, describing every method, parameter type and return value in a machine-readable form.

From that schema, separate codegen backends then generate the actual platform artifacts: Objective-C++ protocols and headers for iOS, Java interfaces and matching JNI bindings for Android. The generated code lands in a build directory and is regenerated on every build, which is why it should never be edited by hand.

3. Writing a TurboModule spec: NativeMyModule.ts

A spec file follows a strict, restricted subset of TypeScript so that codegen can reliably parse it. Allowed are certain primitive types, arrays, objects with a fixed shape, and a few special types like Double or UnsafeObject for cases with no fixed structure. Generic TypeScript features like union types with more than two options or complex mapped types are deliberately not supported.

The example below shows a minimal, valid spec file with one synchronous and one asynchronous method, exactly as codegen interprets it as the contract between JavaScript and the native side.

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

export interface Spec extends TurboModule {
  getDeviceId(): string;
  getBatteryLevel(): Promise<number>;
  multiply(a: number, b: number): number;
}

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

4. The generated code in detail: schema, headers and interfaces

For the example module, codegen produces, among other things, a JSON schema file with the abstract method description, an Objective-C++ protocol NativeMyModuleSpec with exactly matching method signatures for iOS, and a Java interface NativeMyModuleSpec for Android that the native class must implement. Both generated interfaces mirror the TypeScript spec exactly, apart from type conversion.

Importantly, these generated files are pure contracts, not implementations. The actual native class must implement the generated interface, and the compiler reports an error as soon as a method is missing or has the wrong signature, something that simply did not exist in the old, manually maintained bridging world.

5. Implementation on iOS: Objective-C++ against the generated protocol

The iOS implementation subclasses NSObject, conforms to the generated protocol NativeMyModuleSpec, and implements every method with an exactly matching signature. For asynchronous methods like getBatteryLevel, the generated code already handles conversion into a JavaScript promise, the native implementation only needs to call resolve or reject.

The module is registered through the generated factory method getTurboModule, which the TurboModuleManager calls on first access from JavaScript. Unlike old native modules, there is no manual RCT_EXPORT_METHOD macro needed for every single method, since the full method list is already known from the spec.

6. Implementation on Android: Kotlin against the generated Java interface

On Android, the Kotlin class implements the generated interface NativeMyModuleSpec, derived from the abstract base class ReactContextBaseJavaModule. Every method must exactly match the generated signature, including the Promise parameter required for asynchronous methods.

Registration happens through a TurboReactPackage that returns an instance of the class in its getModule method and supplies metadata for turbo module discovery via getReactModuleInfoProvider. If either piece is missing, the TurboModuleManager fails to find the module at runtime, but reports a clear error instead of a silent failure.

7. Registration, podspec and autolinking

For codegen to find a module at all, the podspec on iOS or the build.gradle on Android must point to the codegen configuration, usually through an entry in package.json under codegenConfig that declares the name and path of the spec files. React Native autolinking scans this configuration automatically on every build and wires in new modules without requiring manual changes to native project files.

For local modules within a monorepo that are not published as a separate npm package, a matching codegenConfig entry in the app's own package.json is enough, as long as the spec file is discoverable via the configured jsSrcsDir.

8. Type safety: which errors codegen catches at build time

Codegen mainly catches structural errors: missing methods, wrong parameter counts, incompatible types between the spec and the native implementation, and forgotten promise parameters on asynchronous methods. This class of bugs regularly caused crashes in the old architecture that only surfaced when the affected method was actually called, often far away from the actual implementation site.

What is not caught, however, are semantic errors, for example a method that according to the spec returns a valid device ID but actually returns an empty string. Codegen only checks the structure of the contract, not its content, which is why unit tests for the actual business logic remain necessary.

9. Workflow tips: monorepos, local libraries and debugging codegen errors

In a monorepo with multiple packages, it pays off to consistently bundle spec files in a dedicated specs directory per package and point the codegenConfig entry at it, instead of scattering spec files next to arbitrary other code. That makes it much easier to quickly find the affected file after a failed codegen run.

Codegen errors usually show up as cryptic parser errors with a line number in the generated intermediate representation, not directly in the spec file. In practice it helps to progressively simplify suspicious TypeScript constructs like complex union types or optional, nested objects until the codegen run succeeds again, and then reintroduce complexity in a controlled way.

10. Summary

11. FAQ: Codegen for TurboModules at a Glance