React Native Codegen Tools

Common errors

• error: Type 'Int32' is not assignable to type 'number'.

  cause Using `Int32` or other codegen-specific types directly in TypeScript/Flow code that isn't intended for the spec file, or incorrect environment setup.
  fix Ensure `Int32` and similar types are only used within the `TurboModule` or `FabricComponent` spec files. For regular JavaScript/TypeScript, use standard number types. Also, verify your TypeScript `tsconfig.json` or Flow config properly recognizes the codegen type definitions.

• Command failed with exit code 1

  cause A generic error indicating that the `codegen-native-modules` command encountered an issue, often due to malformed spec files, missing dependencies, or incorrect paths.
  fix Inspect the console output preceding the error for more specific messages (e.g., parsing errors, unsupported types, file access issues). Double-check your spec files for syntax errors and ensure all required tools (e.g., `clang`, Java SDK) are correctly installed and configured in your environment.

• Cannot find module 'react-native-codegen/lib/cli/index' or similar path.

  cause Mismatched `react-native-codegen` and `react-native` versions, incorrect import paths in custom scripts, or `node_modules` corruption.
  fix Run `npm install` or `yarn install` to ensure all dependencies are correctly linked. Verify your `react-native-codegen` version is compatible with your `react-native` version. If using custom scripts, ensure the import path precisely matches the package's internal structure for that version.

• Expected a call signature, but got a Flow type annotation. Did you mean to use 'function' instead of 'interface'?

  cause This error typically occurs when a TypeScript or Flow spec file intended for codegen has syntax that the codegen parser doesn't understand or misinterprets.
  fix Review the official React Native documentation for the exact syntax required for TurboModule and Fabric Component spec files. Ensure you are using the correct type annotations and interface definitions as expected by `react-native-codegen`.

Warnings

• breaking Projects upgrading to React Native versions 0.68 and above (which include `react-native-codegen`) must adopt the "New Architecture" (TurboModules/Fabric) for native modules and components. Legacy native modules will typically require significant refactoring or the use of compatibility layers. This is a fundamental shift in how native modules are defined and integrated.
  Fix: Consult the React Native 'New Architecture' migration guide and adapt native module definitions to use the codegen-compatible Flow or TypeScript spec files. Ensure your native module code implements the generated interfaces.
• gotcha The `react-native-codegen` package is tightly coupled with the `react-native` package. Using a `react-native-codegen` version incompatible with your `react-native` version (e.g., from a different major series like `0.70.x` with `0.85.x`) will almost certainly lead to build failures due to API mismatches or schema inconsistencies.
  Fix: Always install `react-native-codegen` as a `devDependency` and ensure its version aligns with the `react-native` version specified in your `package.json`. It's usually managed automatically by the `react-native` CLI.
• gotcha The Flow/TypeScript spec file format used for defining TurboModules and Fabric Components can evolve between React Native minor and major versions. Changes to type definitions, allowed syntax, or structural requirements in these spec files can break code generation.
  Fix: Always consult the official React Native documentation and migration guides for specific `react-native` releases to ensure your spec files remain compatible with the current `react-native-codegen` expectations. Keep your spec files as close to the provided examples as possible.
• gotcha Ensure the `npx react-native codegen-native-modules` command (or `yarn react-native codegen-native-modules`) is executed in the correct project root, with all necessary `--platform` flags (e.g., `ios`, `android`), for the generated native code to be correctly created and linked into your native builds.
  Fix: Verify your `package.json` scripts and CI/CD pipelines correctly invoke the codegen command. Incorrect `project-root` or missing platform flags can lead to missing generated files and subsequent native build errors.

Install

• npm install react-native-codegen npm
• yarn add react-native-codegen yarn
• pnpm add react-native-codegen pnpm

Imports

• generateFromSchema

  import { generateFromSchema } from 'react-native-codegen/lib/generators/GenerateFromSchema';

  This function is primarily for internal React Native tools or advanced custom build scripts, not for typical application development. It's the core programmatic interface for triggering code generation from a schema.
• CodegenConfig

  import type { CodegenConfig } from 'react-native-codegen/lib/cli/types';

  This type definition (or similar) is used internally to define the configuration structure for the codegen CLI. While not typically imported by app developers, it's relevant for those extending the codegen process or building custom tools that interact with it programmatically.
• cli

  import * as cli from 'react-native-codegen/lib/cli';

  This import provides programmatic access to the CLI entry points and utilities. It's generally used for integration into larger build systems or custom scripts, rather than directly within a typical React Native application.

Quickstart

This quickstart demonstrates how to define a TurboModule spec file using TypeScript, which `react-native-codegen` processes to generate native code, and how to trigger the generation via the React Native CLI.

import type { TurboModule } from 'react-native';
import type { Int32 } from 'react-native/Libraries/Types/CodegenTypes';

// native_modules/MyNativeModule/NativeMyNativeModule.ts

/**
 * This is the interface for your native module, defining methods and constants.
 * The codegen tool reads this TypeScript (or Flow) spec file.
 */
export interface Spec extends TurboModule {
  /**
   * Say hello to the native side.
   * @returns A greeting string from native.
   */
  sayHello(): Promise<string>;
  /**
   * Adds two integers on the native side.
   * @param a The first integer.
   * @param b The second integer.
   * @returns The sum of a and b.
   */
  add(a: Int32, b: Int32): Int32;
  /**
   * Returns a constant object.
   */
  getConstants(): {
    DEFAULT_VALUE: string;
  };
}

// Declare the global TurboModule proxy for type safety
declare global {
  var __turboModuleProxy: (moduleName: string) => Spec | null;
}

// --- To generate native code, run this command in your project root ---
// npx react-native codegen-native-modules \ 
//   --platform ios \ 
//   --platform android \ 
//   --project-root . \ 
//   --output-dir ./node_modules/my-native-module/generated

// (Note: The --output-dir is illustrative; in a real project, this might be managed by the CLI)