React Native Academy · Lección

Escritura de un módulo nativo heredado en Kotlin

Cree un ReactContextBaseJavaModule en Kotlin, anote un método con @ReactMethod, expóngalo mediante un ReactPackage y llámelo desde JavaScript.

Escritura de un módulo nativo heredado en Kotlin es una lección gratuita de React Native Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de React Native Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de React Native Academy incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

What Is a Legacy Native Module

A legacy native module allows you to call native Android (Kotlin/Java) code from JavaScript in a React Native app. When the built-in React Native APIs do not cover a device feature you need, you write a native module to bridge the gap. Legacy modules use the Bridge architecture, which means calls go asynchronously across the JS-to-native bridge.

Creating the Kotlin Module Class

Every Android native module extends ReactContextBaseJavaModule. You override getName() to return the name that JavaScript will use to call your module. Place this class inside the android/app/src/main/java/com/yourapp/ folder alongside existing Android source files.

// ToastModule.kt
package com.yourapp

import android.widget.Toast
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.bridge.ReactContextBaseJavaModule
import com.facebook.react.bridge.ReactMethod

class ToastModule(reactContext: ReactApplicationContext) :
    ReactContextBaseJavaModule(reactContext) {

    override fun getName(): String = 'ToastModule'
}

Annotating Methods with @ReactMethod

Any method you want to expose to JavaScript must be annotated with @ReactMethod. The method must be public and its return type must be void — results are returned asynchronously via callbacks or promises, not return values. React Native serializes parameters automatically for basic types like String, Int, Boolean, and Double.

@ReactMethod
fun show(message: String, duration: Int) {
    val durationConst = if (duration == Toast.LENGTH_SHORT)
        Toast.LENGTH_SHORT else Toast.LENGTH_LONG
    Toast.makeText(reactApplicationContext, message, durationConst).show()
}

Creating the ReactPackage

Native modules must be registered through a ReactPackage. You implement the ReactPackage interface and return your module from createNativeModules. The package is then added to the list of packages in MainApplication.kt so React Native includes it at startup.

// ToastPackage.kt
package com.yourapp

import com.facebook.react.ReactPackage
import com.facebook.react.bridge.NativeModule
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.uimanager.ViewManager

class ToastPackage : ReactPackage {
    override fun createNativeModules(
        reactContext: ReactApplicationContext
    ): List<NativeModule> = listOf(ToastModule(reactContext))

    override fun createViewManagers(
        reactContext: ReactApplicationContext
    ): List<ViewManager<*, *>> = emptyList()
}

Registering the Package in MainApplication

Open MainApplication.kt and find the getPackages() method. Add an instance of your ToastPackage to the list. React Native calls this during startup to discover all available native modules and register their JavaScript interfaces.

// MainApplication.kt (inside getPackages)
override fun getPackages(): List<ReactPackage> =
    PackageList(this).packages.apply {
        add(ToastPackage()) // <-- register your package here
    }

Calling the Module from JavaScript

On the JavaScript side, import NativeModules from react-native and access your module by the name returned from getName(). Wrap the native module in a helper file to provide a clean TypeScript API and hide the raw NativeModules reference from your components.

// ToastModule.js
import { NativeModules } from 'react-native';

const { ToastModule } = NativeModules;

export function showToast(message, duration = 'short') {
  const dur = duration === 'short' ? 0 : 1;
  ToastModule.show(message, dur);
}

// Usage in a component:
// import { showToast } from './ToastModule';
// showToast('Hello from native!', 'long');

Returning Values with Promises

Because @ReactMethod methods must return void, you use Promise parameters to send data back to JavaScript. Add promise: Promise as the last parameter, call promise.resolve(value) on success, or promise.reject(code, message) on error. On the JS side you await the call like any async function.

// Kotlin
@ReactMethod
fun getDeviceName(promise: Promise) {
    try {
        val name = android.os.Build.MODEL
        promise.resolve(name)
    } catch (e: Exception) {
        promise.reject('ERROR', e.message)
    }
}

// JavaScript
const name = await NativeModules.MyModule.getDeviceName();
console.log('Device:', name);

Using Callbacks as an Alternative

Before Promises became standard, native modules used Callback parameters (Callback type in the SDK). You receive one or two callbacks — typically successCallback and errorCallback — and invoke them from native code. Callbacks can only be called once; use Promises or events for repeated responses.

@ReactMethod
fun getBatteryLevel(
    successCallback: Callback,
    errorCallback: Callback
) {
    try {
        val intent = reactApplicationContext.registerReceiver(
            null,
            android.content.IntentFilter(
                android.content.Intent.ACTION_BATTERY_CHANGED
            )
        )
        val level = intent?.getIntExtra(
            android.os.BatteryManager.EXTRA_LEVEL, -1
        ) ?: -1
        successCallback.invoke(level)
    } catch (e: Exception) {
        errorCallback.invoke(e.message)
    }
}

Passing Complex Data with WritableMap

To return an object (JSON map) from native to JavaScript, use WritableMap and Arguments.createMap(). You add key-value pairs to the map using typed putters like putString, putInt, and putBoolean. The map is automatically serialized into a JavaScript object when it reaches the JS layer.

@ReactMethod
fun getDeviceInfo(promise: Promise) {
    val map = Arguments.createMap()
    map.putString('model', android.os.Build.MODEL)
    map.putString('brand', android.os.Build.BRAND)
    map.putInt('sdkVersion', android.os.Build.VERSION.SDK_INT)
    map.putBoolean('isTablet', reactApplicationContext
        .resources.configuration.smallestScreenWidthDp >= 600)
    promise.resolve(map)
}

The isBlockingSynchronousMethod Annotation

By default all @ReactMethod calls are asynchronous. Adding isBlockingSynchronousMethod = true makes the call synchronous — the JS thread blocks until native returns. This is strongly discouraged in production because it freezes the UI, but it can be useful for debugging or reading a tiny cached value that must be available immediately.

@ReactMethod(isBlockingSynchronousMethod = true)
fun getAppVersionSync(): String {
    return reactApplicationContext
        .packageManager
        .getPackageInfo(reactApplicationContext.packageName, 0)
        .versionName ?: 'unknown'
}

Module Constants via getConstants

You can expose compile-time constants to JavaScript by overriding getConstants() in your module. Constants are transferred once at startup and are synchronously accessible as NativeModules.MyModule.CONSTANT_NAME with no async call needed. Use constants for fixed values like error codes, config flags, or platform identifiers.

override fun getConstants(): Map<String, Any> {
    return mapOf(
        'LONG_TOAST' to Toast.LENGTH_LONG,
        'SHORT_TOAST' to Toast.LENGTH_SHORT,
        'PLATFORM' to 'android'
    )
}

// In JavaScript:
// const { LONG_TOAST } = NativeModules.ToastModule;
// showToast('Hello!', LONG_TOAST);

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

In this lesson you learned: how to create a ReactContextBaseJavaModule in Kotlin, annotate methods with @ReactMethod to expose them to JavaScript, and register the module through a ReactPackage in MainApplication. You also saw how to return data using Promises and WritableMap. Next up we explore writing a legacy native module in Swift for iOS.

Preguntas frecuentes

¿La lección «Escritura de un módulo nativo heredado en Kotlin» es gratis?

Sí — el texto completo de «Escritura de un módulo nativo heredado en Kotlin» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de React Native Academy, actualiza a CoddyKit PRO. El curso de React Native Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Escritura de un módulo nativo heredado en Kotlin»?

Cree un ReactContextBaseJavaModule en Kotlin, anote un método con @ReactMethod, expóngalo mediante un ReactPackage y llámelo desde JavaScript. Practicas React Native Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar React Native Academy?

No se requiere experiencia previa. React Native Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Escritura de un módulo nativo heredado en Kotlin»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de React Native Academy?

Sí. Cada lección de React Native Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Escritura de un módulo nativo heredado en Kotlin
Escritura de un módulo nativo heredado en Swift
Módulos nativos Turbo con JSI
Callbacks asíncronos, Promises y eventos desde código nativo

← Volver a React Native Academy