Rumo a uma API JavaScript estável (novas alterações em 0.80)

12 de junho de 2025 · 10 min de leitura

No React Native 0.80, estamos introduzindo duas mudanças significativas na API JavaScript do React Native — a descontinuação das importações profundas e nossa nova API Strict TypeScript. Elas fazem parte de um esforço contínuo para definir com precisão nossa API e oferecer segurança de tipo confiável para usuários e estruturas.

Conclusões rápidas:

• Profunda depreciação das importações: A partir de 0,80, estamos introduzindo avisos de depreciação para importações profundas do react-native pacote.
• API TypeScript estrita de opt-in: Estamos migrando para tipos TypeScript de origem e uma nova linha de base de API pública em TypeScript. Elas permitem uma precisão de tipo mais forte e preparada para o futuro, e serão uma mudança única e revolucionária. Optar por participar através de compilerOptions no seu projeto tsconfig.json.
• Trabalharemos com a comunidade ao longo do tempo para garantir que essas alterações funcionem para todos, antes de habilitar a API Strict TypeScript por padrão em uma versão futura do React Native.

O que está mudando e por quê

Estamos nos movendo para melhorar e estabilizar a API JavaScript pública do React Native — ou seja, o que você obtém ao importar 'react-native'.

Historicamente, aproximamos isso. React Native é de autoria em Fluxo, mas a comunidade há muito mudou para TypeScript em código aberto, que é como a API pública é consumida e validada para compatibilidade. Nossos tipos têm sido (amorosamente) contribuído pela comunidade, e desde então mesclados e alinhados em nossa base de código. No entanto, estes dependeram de manutenção manual e de nenhuma ferramenta automatizada, introduzindo lacunas de correção.

Além disso, nossa API JS pública foi mal definida em termos de limites de módulo — por exemplo, interno 'react-native/Libraries/' importações profundas podiam ser acessadas pelo código do aplicativo, mas podiam mudar com frequência conforme atualizávamos esses componentes internos.

Na versão 0.80, estamos abordando esses problemas descontinuando importações profundas e introduzindo uma opção de usuário para uma nova linha de base de API gerada no TypeScript. Estamos chamando isso de nosso API TypeScript estrita. Em última análise, esta é a base para oferecer uma API React Native estável no futuro.

Importações profundas e depreciativas de react-native

A principal mudança que estamos fazendo em nossa API hoje é descontinuar o uso de importações profundas (RFC), com avisos no ESLint e no console JS. As importações profundas de valores e tipos devem ser atualizadas para react-nativeimportação raiz de 's.

// Before - import from subpath
import {Alert} from 'react-native/Libraries/Alert/Alert';

// After - import from `react-native`
import {Alert} from 'react-native';

Essa alteração reduz a área total da nossa API JavaScript em um conjunto fixo de exportações que podemos controlar e tornar estáveis em uma versão futura. Nosso objetivo é remover esses caminhos de importação na versão 0.82.

Feedback da API

Algumas APIs não são exportadas no root e ficarão indisponíveis sem importações profundas. Temos um abrir tópico de feedback e trabalharemos com a comunidade para finalizar as exportações em nossa API pública. Por favor, compartilhe seu feedback!

Optando por não participar

Tenha em mente que pretendemos remover importações profundas da API do React Native em uma versão futura e, em vez disso, elas devem ser atualizadas para a importação raiz.

Optar por não receber avisos

ESLint

Desativar o no-deep-imports regra usando overrides.

.eslintrc.js

overrides: [
    {
      files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
      rules: {
        '@react-native/no-deep-imports': 0,
      },
    },
  ]

Avisos do console

Passe o disableDeepImportWarnings opção para @react-native/babel-preset.

babel.config.js

module.exports = {
  presets: [
    ['module:@react-native/babel-preset', {disableDeepImportWarnings: true}]
  ],
};

Reinicie seu aplicativo com --reset-cache para limpar o cache do Metro.

npx @react-native-community/cli start --reset-cache

Optar por não receber avisos (Expo)

ESLint

Desativar o no-deep-imports regra usando overrides.

.eslintrc.js

overrides: [
  {
    files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
    rules: {
      '@react-native/no-deep-imports': 0,
    },
  },
];

Avisos do console

Passe o disableDeepImportWarnings opção para babel-preset-expo.

babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [['babel-preset-expo', {disableDeepImportWarnings: true}]],
  };
};

Reinicie seu aplicativo com --clear para limpar o cache do Metro.

npx expo start --clear

API TypeScript estrita (opt-in)

A API Strict TypeScript é um novo conjunto de tipos TypeScript no react-native pacote, que pode ser optado através do seu tsconfig.json. Estamos enviando-os junto com nossos tipos de TS existentes, o que significa que você pode optar por migrar quando estiver pronto.

Os novos tipos são:

1. Gerado diretamente a partir do nosso código fonte — melhorando a cobertura e a correção, para que você possa esperar garantias de compatibilidade mais fortes.
2. Restrito a react-nativearquivo de índice 's — definindo mais rigorosamente nossa API pública, o que significa que não quebraremos a API ao fazer alterações internas no arquivo.

Quando a comunidade estiver pronta, a API Strict TypeScript se tornará nossa API padrão no futuro — sincronizada com a remoção profunda de importações. Isso significa que é um boa ideia para começar a optar, pois você estará pronto para a futura API JS estável do React Native.

tsconfig.json

{
  "extends": "@react-native/typescript-config",
  "compilerOptions": {
    ...
    "customConditions": ["react-native-strict-api"]
  }
}

Sob o capô

Isso instruirá o TypeScript a resolver react-native tipos do nosso novo types_generated/ dir, em vez do anterior types/ dir (mantido manualmente). Não é necessário reiniciar o TypeScript ou seu editor.

Últimas notícias: Importações profundas não são permitidas

Como acima, os tipos sob a API Strict TypeScript agora só podem ser resolvidos a partir do principal 'react-native' caminho de importação, aplicando encapsulamento de pacotes, conforme nossa depreciação acima.

// Before - import from subpath
import {Alert} from 'react-native/Libraries/Alert/Alert';

// After - MUST import from `react-native`
import {Alert} from 'react-native';

Vitória chave

Nós definimos o escopo da nossa API pública para as exportações do React Native index.js arquivo, que mantemos cuidadosamente. Isso significa que alterações de arquivo em outras partes da nossa base de código não farão mais alterações de quebra.

Quebra: Alguns nomes / formas de tipos mudaram

Os tipos agora são gerados a partir da fonte, em vez de mantidos manualmente. Ao fazer isso:

• Alinhamos as diferenças que surgiram a partir dos tipos contribuídos pela comunidade — e também aumentamos a cobertura de tipos do nosso código-fonte.
• Atualizamos intencionalmente alguns nomes de tipos e formas de tipos, onde havia espaço para simplificar ou reduzir a ambiguidade.

Vitória chave

Como os tipos agora são gerados a partir do código-fonte do React Native, você pode ter certeza de que o verificador de tipos é sempre preciso para uma determinada versão de react-native.

Exemplo: Símbolos exportados mais rigorosos

O Linking API agora é única interface, em vez de duas exportações. Isto se segue para uma série de outras APIs (veja os documentos).

// Before
import {Linking, LinkingStatic} from 'react-native';

function foo(linking: LinkingStatic) {}
foo(Linking);

// After
import {Linking} from 'react-native';

function foo(linking: Linking) {}
foo(Linking);

Exemplo: Tipos fixos / mais completos

Definições manuais de tipo anteriores deixaram a oportunidade de lacunas de tipo. No Flow → TypeScript gerado, eles não estão mais presentes (e, na origem, se beneficiam da validação de tipo adicional do Flow para código multiplataforma).

import {Dimensions} from 'react-native';

// Before - Type error
// After - number | undefined
const {densityDpi} = Dimensions.get();

Outras mudanças de última hora

Por favor, consulte nosso guia dedicado nos documentos que detalham todas as alterações de tipos de quebra e como atualizar seu código.

Implementação

Agradecemos que qualquer alteração drástica no React Native levará tempo para que os desenvolvedores atualizem seus aplicativos.

Agora — Lançamento opt-in (0,80)

O "react-native-strict-api" opt-in é estável na versão 0.80.

• Esta é uma migração única. Nosso objetivo é que aplicativos e bibliotecas optem por participar em seu próprio ritmo nos próximos lançamentos.
• Em qualquer modo, nada mudará para seu aplicativo em tempo de execução — isso afeta apenas a análise TypeScript.
• E, receberemos feedback sobre APIs ausentes, por meio de nosso tópico de feedback dedicado.

Recomendado

A API Strict TypeScript se tornará nossa API padrão no futuro.

Se você tiver tempo, vale a pena testar o opt-in agora em seu tsconfig.json, para preparar seu aplicativo ou biblioteca para o futuro. Isso avaliará imediatamente se há algum tipo de erro introduzido em seu aplicativo sob a API Strict. Pode não haver nenhum(!) — nesse caso, você está pronto para ir.

Futuro — API TypeScript estrita por padrão

No futuro, exigiremos que todas as bases de código usem nossa API Strict e removeremos os tipos legados.

O cronograma para isso será baseado no feedback da comunidade. Pelo menos nas próximas duas versões do React Native, a Strict API continuará sendo uma opção opcional.

Perguntas frequentes

Estou usando importações de subcaminhos hoje. O que devo fazer?

Por favor, migre para a raiz 'react-native' caminho de importação.

• Importações de subcaminhos (por exemplo 'react-native/Libraries/Alert/Alert') estão se tornando APIs privadas. Sem impedir o acesso a arquivos de implementação dentro do React Native, não podemos oferecer uma API JavaScript estável.
• Queremos que nossos avisos de depreciação motivem o feedback da comunidade, que pode ser gerado por meio de nossos tópico de discussão centralizado, se você acredita que não estamos expondo caminhos de código que são cruciais para seu aplicativo. Quando justificado, podemos promover APIs para a exportação de índice.

Sou mantenedor de biblioteca. Como essa mudança me afeta?

Tanto os aplicativos quanto as bibliotecas podem optar por participar em seu próprio ritmo, já que tsconfig.json afetará apenas a base de código imediata.

• Normalmente, node_modules é excluído da validação pelo servidor TypeScript em um projeto React Native. Portanto, as definições de tipo exportadas do seu pacote são a fonte da verdade.

💡 Queremos feedback! Tal como acontece com as importações de subcaminhos alteradas, se você encontrar algum problema de integração com a API Strict, informe-nos no GitHub.

Isso já garante uma API final para React Native?

Infelizmente, ainda não. Na versão 0.80, fizemos um investimento em ferramentas para que a linha de base da API JS existente do React Native possa ser consumida com precisão via TypeScript — , permitindo futuras alterações estáveis. Estamos formalizando a API existente que você conhece e adora.

No futuro, tomaremos medidas para finalizar as APIs que oferecemos atualmente no core — em cada superfície de linguagem. As alterações na API serão comunicadas por meio de RFCs/anúncios e, normalmente, de um ciclo de descontinuação.

Por que o React Native não é escrito em TypeScript?

React Native é a infraestrutura central da Meta. Testamos todas as alterações mescladas em nossa Família de Aplicativos antes que elas atinjam a disponibilidade geral de código aberto.

Nessa escala e sensibilidade, a correção é importante. O ponto principal é que o Flow nos oferece maior desempenho e maior rigor do que o TypeScript, incluindo suporte multiplataforma para React Native.

Obrigado

Essas mudanças foram possíveis graças a Praça Iwo, Jakub Piasecki, Dawid Małecki, Alex Caça, e Riccardo Cipolleschi.

Obrigado também a Pieter Vanderwerff, Rubén Norte, e Rob Hogan por sua ajuda e contribuição adicionais.

Saiba mais

Assista à palestra!Compartilhamos um mergulho profundo em nossas motivações e no trabalho por trás da API Strict TypeScript em App.js 2025.Ver no YouTube