App:

Native Modules

Your React Native application code may need to interact with native platform APIs that aren't provided by React Native or an existing library. You can write the integration code yourself using a Turbo Native Module. This guide will show you how to write one.

The basic steps are:

define a typed JavaScript specification using one of the most popular JavaScript type annotation languages: Flow or TypeScript; configure your dependency management system to run Codegen, which converts the specification into native language interfaces; write your application code using your specification; and write your native platform code using the generated interfaces to write and hook your native code into the React Native runtime environment. Lets work through each of these steps by building an example Turbo Native Module. The rest of this guide assume that you have created your application running the command:

shell npx @react-native-community/cli@latest init TurboModuleLocalStorage --version 0.76.0

Native Persistent Storage

This guide will show you how to write an implementation of the Web Storage API: localStorage. The API is relatable to a React developer who might be writing application code on your project.

To make this work on mobile, we need to use Android and iOS APIs:

Android: SharedPreferences, and iOS: NSUserDefaults.

1. Declare Typed Specification

React Native provides a tool called Codegen, which takes a specification written in TypeScript or Flow and generates platform specific code for Android and iOS. The specification declares the methods and data types that will pass back and forth between your native code and the React Native JavaScript runtime. A Turbo Native Module is both your specification, the native code you write, and the Codegen interfaces generated from your specification.

To create a specs file:

Inside the root folder of your app, create a new folder called specs. Create a new file called NativeLocalStorage.ts. info You can see all of the types you can use in your specification and the native types that are generated in the Appendix documentation.

Here is an implementation of the localStorage specification:

specs/NativeLocalStorage.ts

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

export interface Spec extends TurboModule {
  setItem(value: string, key: string): void;
  getItem(key: string): string | null;
  removeItem(key: string): void;
  clear(): void;
}

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

2. Configure Codegen to run

The specification is used by the React Native Codegen tools to generate platform specific interfaces and boilerplate for us. To do this, Codegen needs to know where to find our specification and what to do with it. Update your package.json to include:

package.json
     "start": "react-native start",
     "test": "jest"
   },
   "codegenConfig": {
     "name": "NativeLocalStorageSpec",
     "type": "modules",
     "jsSrcsDir": "specs",
     "android": {
       "javaPackageName": "com.nativelocalstorage"
     }
   },
   "dependencies": {

With everything wired up for Codegen, we need to prepare our native code to hook into our generated code.

a. ANDROID

Codegen is executed through the generateCodegenArtifactsFromSchema Gradle task:

bash

cd android
./gradlew generateCodegenArtifactsFromSchema

BUILD SUCCESSFUL in 837ms 14 actionable tasks: 3 executed, 11 up-to-date

This is automatically run when you build your Android application.

b. iOS

Codegen is run as part of the script phases that's automatically added to the project generated by CocoaPods.

bash

cd ios
bundle install
bundle exec pod install

The output will look like this:

...
Framework build type is static library
[Codegen] Adding script_phases to ReactCodegen.
[Codegen] Generating ./build/generated/ios/ReactCodegen.podspec.json
[Codegen] Analyzing /Users/me/src/TurboModuleExample/package.json
[Codegen] Searching for codegen-enabled libraries in the app.
[Codegen] Found TurboModuleExample
[Codegen] Searching for codegen-enabled libraries in the project dependencies.
[Codegen] Found react-native
...

3. Write Application Code using the Turbo Native Module

Using NativeLocalStorage, here’s a modified App.tsx that includes some text we want persisted, an input field and some buttons to update this value.

The TurboModuleRegistry supports 2 modes of retrieving a Turbo Native Module:

get(name: string): T | null which will return null if the Turbo Native Module is unavailable. getEnforcing(name: string): T which will throw an exception if the Turbo Native Module is unavailable. This assumes the module is always available.

App.tsx

import React from 'react';
import {
  View,
  StyleSheet,
  Text,
  TextInput,
  Button,
} from 'react-native';

import NativeLocalStorage from './specs/NativeLocalStorage';

const EMPTY = '<empty>';

function App(): React.JSX.Element {
  const [value, setValue] = React.useState<string | null>(null);

  const [editingValue, setEditingValue] = React.useState<
    string | null
  >(null);

  React.useEffect(() => {
    const storedValue = NativeLocalStorage?.getItem('myKey');
    setValue(storedValue ?? '');
  }, []);

  function saveValue() {
    NativeLocalStorage?.setItem(editingValue ?? EMPTY, 'myKey');
    setValue(editingValue);
  }

  function clearAll() {
    NativeLocalStorage?.clear();
    setValue('');
  }

  function deleteValue() {
    NativeLocalStorage?.removeItem('myKey');
    setValue('');
  }

  return (
    <View style={{flex: 1}}>
      <Text style={styles.text}>
        Current stored value is: {value ?? 'No Value'}
      </Text>
      <TextInput
        placeholder="Enter the text you want to store"
        style={styles.textInput}
        onChangeText={setEditingValue}
      />
      <Button title="Save" onPress={saveValue} />
      <Button title="Delete" onPress={deleteValue} />
      <Button title="Clear" onPress={clearAll} />
    </View>
  );
}

const styles = StyleSheet.create({
  text: {
    margin: 10,
    fontSize: 20,
  },
  textInput: {
    margin: 10,
    height: 40,
    borderColor: 'black',
    borderWidth: 1,
    paddingLeft: 5,
    paddingRight: 5,
    borderRadius: 5,
  },
});

export default App;

4.a Write your Native Platform code - ANDROID

With everything prepared, we're going to start writing native platform code. We do this in 2 parts:

note This guide shows you how to create a Turbo Native Module that only works with the New Architecture. If you need to support both the New Architecture and the Legacy Architecture, please refer to our backwards compatibility guide.

Now it's time to write some Android platform code to make sure localStorage survives after the application is closed.

The first step is to implement the generated NativeLocalStorageSpec interface:

android/app/src/main/java/com/nativelocalstorage/NativeLocalStorageModule.java package com.turbomodulelocalstorage;

import android.content.Context;
import android.content.SharedPreferences;
import com.nativelocalstorage.NativeLocalStorageSpec;
import com.facebook.react.bridge.ReactApplicationContext;

public class NativeLocalStorageModule extends NativeLocalStorageSpec {

  public static final String NAME = "NativeLocalStorage";

  public NativeLocalStorageModule(ReactApplicationContext reactContext) {
    super(reactContext);
  }

  @Override
  public String getName() {
    return NAME;
  }

  @Override
  public void setItem(String value, String key) {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    SharedPreferences.Editor editor = sharedPref.edit();
    editor.putString(key, value);
    editor.apply();
  }

  @Override
  public String getItem(String key) {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    String username = sharedPref.getString(key, null);
    return username;
  }

  @Override
  public void removeItem(String key) {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    sharedPref.edit().remove(key).apply();
  }
  @Override
    public void clear() {
        SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
        sharedPref.edit().clear().apply();
   }
}

Next we need to create NativeLocalStoragePackage. It provides an object to register our Module in the React Native runtime, by wrapping it as a Base Native Package:

android/app/src/main/java/com/nativelocalstorage/NativeLocalStoragePackage.java

package com.turbomodulelocalstorage;

import com.facebook.react.BaseReactPackage;
import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.module.model.ReactModuleInfo;
import com.facebook.react.module.model.ReactModuleInfoProvider;

import java.util.HashMap;
import java.util.Map;

public class NativeLocalStoragePackage extends BaseReactPackage {

  @Override
  public NativeModule getModule(String name, ReactApplicationContext reactContext) {
    if (name.equals(NativeLocalStorageModule.NAME)) {
      return new NativeLocalStorageModule(reactContext);
    } else {
      return null;
    }
  }

  @Override
  public ReactModuleInfoProvider getReactModuleInfoProvider() {
    return new ReactModuleInfoProvider() {
      @Override
      public Map<String, ReactModuleInfo> getReactModuleInfos() {
        Map<String, ReactModuleInfo> map = new HashMap<>();
        map.put(NativeLocalStorageModule.NAME, new ReactModuleInfo(
          NativeLocalStorageModule.NAME,       // name
          NativeLocalStorageModule.NAME,       // className
          false, // canOverrideExistingModule
          false, // needsEagerInit
          false, // isCXXModule
          true   // isTurboModule
        ));
        return map;
      }
    };
  }
}

Finally, we need to tell the React Native in our main application how to find this Package. We call this "registering" the package in React Native.

In this case, you add it to be returned by the getPackages method.

info Later you’ll learn how to distribute your Native Modules as npm packages, which our build tooling will autolink for you.

android/app/src/main/java/com/turobmoduleexample/MainApplication.java

package com.turbomodulelocalstorage

import android.app.Application
import com.facebook.react.PackageList
import com.facebook.react.ReactApplication
import com.facebook.react.ReactHost
import com.facebook.react.ReactNativeHost
import com.facebook.react.ReactPackage
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.load
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
import com.facebook.react.defaults.DefaultReactNativeHost
import com.facebook.react.soloader.OpenSourceMergedSoMapping
import com.facebook.soloader.SoLoader
import com.nativelocalstorage.NativeLocalStoragePackage;


class MainApplication : Application(), ReactApplication {

  override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
        override fun getPackages(): List<ReactPackage> =
            PackageList(this).packages.apply {
              // Packages that cannot be autolinked yet can be added manually here, for example:
              // add(MyReactNativePackage())
                add(NativeLocalStoragePackage());
            }

        override fun getJSMainModuleName(): String = "index"

        override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG

        override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
        override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED
      }

  override val reactHost: ReactHost
    get() = getDefaultReactHost(applicationContext, reactNativeHost)

  override fun onCreate() {
    super.onCreate()
    SoLoader.init(this, OpenSourceMergedSoMapping)
    if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
      // If you opted-in for the New Architecture, we load the native entry point for this app.
      load()
    }
  }
}

You can now build and run your code on an emulator:

bash yarn run android

4.b Write your Native Platform code - iOS

With everything prepared, we're going to start writing native platform code. We do this in 2 parts:

note This guide shows you how to create a Turbo Native Module that only works with the New Architecture. If you need to support both the New Architecture and the Legacy Architecture, please refer to our backwards compatibility guide.

Now it's time to write some iOS platform code to make sure localStorage survives after the application is closed.

Prepare your Xcode Project We need to prepare your iOS project using Xcode. After completing these 6 steps you'll have RCTNativeLocalStorage that implements the generated NativeLocalStorageSpec interface.

Open the CocoPods generated Xcode Workspace: bash

cd ios
open TurboModuleExample.xcworkspace

Open Xcode Workspace Right click on app and select New Group, call the new group NativeLocalStorage. Right click on app and select New Group In the NativeLocalStorage group, create New→File from Template. Create a new file using the Cocoa Touch Class template Use the Cocoa Touch Class. Use the Cocoa Touch Class template Name the Cocoa Touch Class RCTNativeLocalStorage with the Objective-C language. Create an Objective-C RCTNativeLocalStorage class Rename RCTNativeLocalStorage.m → RCTNativeLocalStorage.mm making it an Objective-C++ file. Convert to and Objective-C++ file Implement localStorage with NSUserDefaults Start by updating RCTNativeLocalStorage.h:

NativeLocalStorage/RCTNativeLocalStorage.h

//  RCTNativeLocalStorage.h
//  TurboModuleExample

#import <Foundation/Foundation.h>
#import <NativeLocalStorageSpec/NativeLocalStorageSpec.h>

NS_ASSUME_NONNULL_BEGIN

@interface RCTNativeLocalStorage : NSObject
@interface RCTNativeLocalStorage : NSObject <NativeLocalStorageSpec>

@end

Then update our implementation to use NSUserDefaults with a custom suite name.

NativeLocalStorage/RCTNativeLocalStorage.mm
//  RCTNativeLocalStorage.m
//  TurboModuleExample

#import "RCTNativeLocalStorage.h"

static NSString *const RCTNativeLocalStorageKey = @"local-storage";

@interface RCTNativeLocalStorage()
@property (strong, nonatomic) NSUserDefaults *localStorage;
@end

@implementation RCTNativeLocalStorage

- (id) init {
  if (self = [super init]) {
    _localStorage = [[NSUserDefaults alloc] initWithSuiteName:RCTNativeLocalStorageKey];
  }
  return self;
}

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

- (NSString * _Nullable)getItem:(NSString *)key {
  return [self.localStorage stringForKey:key];
}

- (void)setItem:(NSString *)value
          key:(NSString *)key {
  [self.localStorage setObject:value forKey:key];
}

- (void)removeItem:(NSString *)key {
  [self.localStorage removeObjectForKey:key];
}

- (void)clear {
  NSDictionary *keys = [self.localStorage dictionaryRepresentation];
  for (NSString *key in keys) {
    [self removeItem:key];
  }
}

+ (NSString *)moduleName
{
  return @"NativeLocalStorage";
}

@end

Important things to note:

You can use Xcode to jump to the Codegen @protocol NativeLocalStorageSpec. You can also use Xcode to generate stubs for you. Register the Native Module in your app The last step consist in updating the package.json to tell React Native about the link between the JS specs of the Native Module and the concrete implementation of those specs in native code.

Modify the package.json as it follows:

package.json
     "start": "react-native start",
     "test": "jest"
   },
   "codegenConfig": {
     "name": "AppSpecs",
     "type": "modules",
     "jsSrcsDir": "specs",
     "android": {
       "javaPackageName": "com.sampleapp.specs"
     }
     "ios": {
        "modulesProvider": {
          "NativeLocalStorage": "RCTNativeLocalStorage"
        }
    },
   },

   "dependencies": {

At this point, you need to re-install the pods to make sure that codegen runs again to generate the new files:

bash

#from the ios folder
bundle exec pod install
open SampleApp.xcworkspace

If you now build your application from Xcode, you should be able to build successfully.

Build and run your code on a Simulator bash yarn run ios

Reference: https://reactnative.dev/docs/turbo-native-modules-introduction?language=typescript&platforms=android&android-language=java&package-manager=yarn