Turbo Module no React Native — o que é, como funciona o JSI e a arquitetura

O que é Turbo Module?

Turbo Module é um componente da nova arquitetura React Native que substitui o Bridge clássico para a comunicação entre JavaScript e código nativo. Ao contrário do Bridge, onde cada mensagem é serializada em JSON e transmitida de forma assíncrona, o Turbo Module usa JSI — uma camada que permite ao JavaScript chamar diretamente funções escritas em C++.

A arquitetura Turbo Module foi apresentada pela equipe Meta na React Conf 2021 como parte de uma reestruturação maior do React Native sob o codinome «The New Architecture». Além do Turbo Module, a nova arquitetura inclui Fabric (novo renderizador), Codegen (gerador de código) e JSI (interface de interação). Juntos, esses componentes resolvem problemas de desempenho que se acumulavam no React Native desde 2015.

O Turbo Module resolve três problemas principais dos módulos nativos clássicos: assincronicidade (todas as chamadas passam por uma fila), serialização (cada chamada requer transformação JSON) e carregamento (todos os módulos são inicializados na inicialização do aplicativo). Com o Turbo Module, os métodos nativos são chamados de forma síncrona, os dados são transferidos sem cópia e os módulos são carregados sob demanda.

Como funciona o JSI

JSI (JavaScript Interface) é uma API C++ que cria uma camada entre o mecanismo JavaScript (Hermes ou JSC) e o código nativo. O JSI fornece objetos host — objetos C++ que aparecem como objetos e métodos JavaScript comuns. Quando o JavaScript chama um método de tal objeto, o JSI executa diretamente o código C++ correspondente sem serialização e sem troca de thread.

A diferença chave entre JSI e Bridge é a ausência de cópia de dados. No Bridge, cada valor é serializado em uma string JSON, passado por uma fila e desserializado. O JSI passa ponteiros para dados na memória, permitindo trabalhar com grandes volumes de dados sem perda de desempenho. De acordo com os testes da Meta, as chamadas JSI são executadas de 5 a 10 vezes mais rápido que chamadas equivalentes através do Bridge.

HostObject e chamadas síncronas

O JSI define a interface HostObject — uma classe C++ que o React Native registra no ambiente JS como um objeto comum. Quando o código JS acessa uma propriedade ou chama um método do HostObject, o JSI intercepta a chamada e executa o código C++. Isso permite realizar operações de forma síncrona sem esperar a fila do Bridge.

// Exemplo JSI HostObject — chamada nativa síncrona
class ImageCompressorHostObject : public jsi::HostObject {

    jsi::Value get(
        jsi::Runtime& rt,
        const jsi::PropNameID& propName
    ) override {
        auto name = propName.utf8(rt);
        if (name == "compressImage") {
            return jsi::Function::createFromHostFunction(
                rt,
                jsi::PropNameID::forUtf8(rt, name),
                2,
                [](jsi::Runtime& rt,
                   const jsi::Value& thisValue,
                   const jsi::Value* args,
                   size_t count) -> jsi::Value {
                    return jsi::Value(rt, compressNative(
                        args[0].asString(rt).utf8(rt),
                        args[1].asNumber()
                    ));
                }
            );
        }
        return jsi::Value::undefined();
    }
};

O código acima demonstra como o JSI HostObject lida com a chamada compressImage do JavaScript. A função recebe dois argumentos (uma string de caminho e um número de qualidade), chama a função nativa compressNative e retorna o resultado — tudo de forma síncrona, sem Bridge, sem JSON. Esta é a vantagem chave do JSI sobre a arquitetura clássica.

O JSI faz parte do runtime principal do React Native e não depende de um mecanismo JavaScript específico. Ele funciona tanto com Hermes quanto com JavaScriptCore (JSC), fornecendo uma interface unificada para interação com o ambiente nativo.

Turbo Module vs Bridge: comparação

A comparação entre Turbo Module e Bridge mostra a evolução da arquitetura React Native. O Bridge foi projetado para o lançamento rápido do React Native em 2015, mas com o aumento da complexidade das aplicações, suas limitações se tornaram críticas. O Turbo Module resolve esses problemas ao nível da arquitetura.

Na prática, a diferença é mais notável com chamadas frequentes a métodos nativos — por exemplo, ao processar mídia ou trabalhar com GPU. Para chamadas raras (uma vez por sessão), a diferença de desempenho é insignificante. O Turbo Module também simplifica o trabalho com grandes dados binários — imagens, vídeos, protocolos binários — que no Bridge exigiam soluções alternativas com o sistema de arquivos.

Exemplo de criação de Turbo Module

A criação de um Turbo Module começa com a definição de uma especificação em TypeScript. O Codegen gera automaticamente interfaces C++ e stubs Objective-C/Java baseados nesta especificação. Isso muda completamente a abordagem de desenvolvimento — o desenvolvedor descreve a API uma vez e o Codegen cria todo o resto.

// ImageCompressor.ts — especificação Turbo Module
import type { TurboModule } from 'react-native';
import type { Double } from 'react-native/Libraries/Types/CodegenTypes';

export interface Spec extends TurboModule {
  compressImage(
    imagePath: string,
    quality: Double
  ): Promise<string>;
}

Geração de código através do Codegen

Codegen analisa a especificação TypeScript e gera o HostObject C++, o protocolo Objective-C e a interface Java. Ao desenvolvedor resta apenas implementar a lógica nativa. Essa abordagem garante que os tipos no JavaScript e no lado nativo correspondam sempre, eliminando erros de mapeamento manual.

// Implementação TurboModule para iOS (stub gerado)
@interface ImageCompressorModule ()
    RCT_EXPORT_MODULE(ImageCompressor)
@end

@implementation ImageCompressorModule

RCT_EXPORT_METHOD(compressImage:(NSString *)imagePath
                  quality:(NSNumber *)quality
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
    NSData *compressed = [ImageProcessor compressAtPath:imagePath
                                                    quality:quality.doubleValue];
    resolve([NSString stringWithUTF8String:compressed.UTF8String]);
}

@end

Uma vantagem importante é o carregamento lento. O Turbo Module não é inicializado na inicialização do aplicativo, mas é criado apenas no primeiro acesso a partir do JavaScript. Isso reduz o tempo de inicialização do aplicativo em 30–50% em comparação com a abordagem clássica onde todos os módulos nativos são carregados imediatamente.

Migração do Bridge para o Turbo Module

A transição do Bridge para o Turbo Module não requer a reescrita completa do aplicativo. O React Native 0.73+ suporta ambas as arquiteturas em paralelo — os módulos Bridge continuam funcionando e os novos módulos podem ser criados como Turbo Module. Isso permite migrar gradualmente, módulo por módulo.

Para ativar a nova arquitetura em um projeto React Native 0.76+, defina o sinalizador newArchEnabled como true no arquivo react-native.config.js. Depois disso, todos os módulos nativos existentes continuam funcionando através do Bridge e os novos módulos podem ser criados como Turbo Module. O Codegen lida automaticamente com ambas as opções.

// react-native.config.js — ativar nova arquitetura
module.exports = {
  project: {
    ios: {},
    android: {},
  },
  assets: [],
  newArchEnabled: true,
};

Recomenda-se iniciar a migração pelos módulos chamados com mais frequência a partir do JavaScript — são eles que obterão o maior ganho de desempenho. Módulos chamados raramente (uma vez por sessão) podem permanecer no Bridge sem perda significativa de desempenho.

• Codegen — use especificações TypeScript para geração automática de interfaces nativas.
• Testes E2E — verifique o funcionamento dos módulos em ambas as arquiteturas, especialmente após atualizar o React Native.
• Plano de contingência — em caso de problemas com o Turbo Module, você pode voltar temporariamente ao Bridge através de um sinalizador de configuração.