W kierunku stabilnego interfejsu JavaScript API (Nowości w wersji 0.80)

Nieoficjalne Tłumaczenie Beta

Ta strona została przetłumaczona przez PageTurner AI (beta). Nie jest oficjalnie zatwierdzona przez projekt. Znalazłeś błąd? Zgłoś problem →

W React Native 0.80 wprowadzamy dwie znaczące zmiany w interfejsie JavaScript API - wycofanie głębokich importów oraz nowy Strict TypeScript API. To część naszej ciągłej pracy nad precyzyjnym zdefiniowaniem API i zapewnieniem niezawodnego bezpieczeństwa typów użytkownikom oraz frameworkom.

Najważniejsze zmiany:

• Wycofanie głębokich importów: Od wersji 0.80 wprowadzamy ostrzeżenia o wycofaniu dla importów z głębokich ścieżek pakietu react-native.

• Opcjonalne Strict TypeScript API: Przechodzimy na typy TypeScript generowane bezpośrednio ze źródła oraz nową publiczną linię bazową API w TypeScript. Zapewniają one silniejszą i przyszłościową dokładność typów, co będzie jednorazową zmianą łamiącą wsteczną zgodność. Aktywuj poprzez compilerOptions w pliku tsconfig.json twojego projektu.

• Będziemy współpracować ze społecznością, aby upewnić się, że te zmiany działają dla wszystkich, zanim włączymy Strict TypeScript API domyślnie w przyszłej wersji React Native.

Co się zmienia i dlaczego

Pracujemy nad usprawnieniem i stabilizacją publicznego interfejsu JavaScript API React Native - czyli tego, co otrzymujesz podczas importowania 'react-native'.

Historycznie podchodziliśmy do tego przybliżeniowo. React Native jest tworzony w Flow, ale społeczność dawno przeszła na TypeScript w projektach open source, co determinuje sposób korzystania i weryfikacji zgodności publicznego API. Nasze typy były (z oddaniem) dostarczane przez społeczność, a następnie scalane i wyrównywane w kodzie bazowym. Jednakże opierały się one na ręcznej konserwacji bez automatyzacji, co prowadziło do luk w poprawności.

Dodatkowo, nasze publiczne JS API było słabo zdefiniowane pod względem granic modułów - np. wewnętrzne głębokie importy 'react-native/Libraries/' były dostępne w kodzie aplikacji, ale mogły często ulegać zmianom podczas aktualizacji wewnętrznych mechanizmów.

W wersji 0.80 rozwiązujemy te problemy poprzez wycofanie głębokich importów i wprowadzenie opcjonalnej, generowanej linii bazowej API w TypeScript. Nazywamy to naszym Strict TypeScript API. Ostatecznie stanowi to fundament dla stabilnego API React Native w przyszłości.

Wycofanie głębokich importów z react-native

Główna zmiana, którą wprowadzamy w naszym API, to oznaczenie głębokich importów jako przestarzałych (RFC), z ostrzeżeniami w ESLint i konsoli JS. Głębokie importy wartości i typów należy zaktualizować do importu głównego react-native.

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

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

Ta zmiana redukuje całkowitą powierzchnię naszego JavaScript API do stałego zestawu eksportów, który możemy kontrolować i ustabilizować w przyszłych wydaniach. Planujemy usunięcie tych ścieżek importu w wersji 0.82.

Opinia o API

Niektóre interfejsy API nie są eksportowane w głównym module i staną się niedostępne bez głębokich importów. Mamy otwarty wątek dyskusyjny i będziemy współpracować ze społecznością nad finalizacją eksportów w naszym publicznym API. Podziel się swoją opinią!

Rezygnacja z migracji

Pamiętaj, że naszym celem jest usunięcie głębokich importów z API React Native w przyszłej wersji, dlatego należy je zaktualizować do importu głównego.

Opting out of warnings

ESLint

Disable the no-deep-imports rule using overrides.

.eslintrc.js

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

Console warnings

Pass the disableDeepImportWarnings option to @react-native/babel-preset.

babel.config.js

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

Restart your app with --reset-cache to clear the Metro cache.

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

Opting out of warnings (Expo)

ESLint

Disable the no-deep-imports rule using overrides.

.eslintrc.js

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

Console warnings

Pass the disableDeepImportWarnings option to babel-preset-expo.

babel.config.js

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

Restart your app with --clear to clear the Metro cache.

npx expo start --clear

Strict TypeScript API (opcjonalne)

Strict TypeScript API to nowy zestaw typów TypeScript w pakiecie react-native, który można aktywować poprzez plik tsconfig.json. Dostarczamy je równolegle z istniejącymi typami TS, co oznacza, że możesz wybrać moment migracji.

Nowe typy charakteryzują się:

1. Generowaniem bezpośrednio z kodu źródłowego - zwiększają pokrycie i poprawność, co zapewnia silniejsze gwarancje kompatybilności.

2. Ograniczone do pliku index react-native — ściślej definiuje nasze publiczne API, co oznacza, że nie naruszymy API przy zmianach wewnętrznych plików.

Gdy społeczność będzie gotowa, Strict TypeScript API stanie się naszym domyślnym API w przyszłości — w synchronizacji z usuwaniem głębokich importów. Oznacza to, że dobrym pomysłem jest rozpoczęcie włączania tej opcji, ponieważ przygotuje to twoją aplikację na przyszłe stabilne JS API React Native.

tsconfig.json

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

Działanie w tle

To ustawienie nakazuje TypeScriptowi rozwiązywanie typów react-native z nowego katalogu types_generated/ zamiast poprzedniego types/ (utrzymywanego ręcznie). Restart TypeScripta lub edytora nie jest wymagany.

Zmiana łamiąca: Głębokie importy są niedozwolone

Jak wspomniano powyżej, typy w ramach Strict TypeScript API są teraz rozwiązywalne tylko z głównej ścieżki importu 'react-native', wymuszając enkapsulację pakietu, zgodnie z naszą wcześniejszą deprecacją.

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

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

Kluczowa korzyść

Ograniczyliśmy nasze publiczne API do eksportów z pliku index.js React Native, który starannie utrzymujemy. Oznacza to, że zmiany w innych plikach naszej bazy kodu nie będą już zmianami łamiącymi.

Zmiana łamiąca: Niektóre nazwy i kształty typów uległy zmianie

Typy są teraz generowane ze źródła, a nie utrzymywane ręcznie. Dzięki temu:

• Wyrównaliśmy różnice, które nagromadziły się w typach dostarczanych przez społeczność — a także zwiększyliśmy pokrycie typami naszego kodu źródłowego.

• Celowo zaktualizowaliśmy niektóre nazwy i kształty typów tam, gdzie istniała możliwość uproszczenia lub zmniejszenia niejednoznaczności.

Kluczowa korzyść

Ponieważ typy są teraz generowane z kodu źródłowego React Native, możesz mieć pewność, że sprawdzanie typów jest zawsze dokładne dla danej wersji react-native.

Przykład: Surowsze eksportowane symbole

API Linking jest teraz pojedynczym interface, a nie dwoma eksportami. Podobnie jest z wieloma innymi interfejsami API (zobacz dokumentację).

// 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);

Przykład: Naprawione / bardziej kompletne typy

Poprzednie ręczne definicje typów pozostawiały możliwość wystąpienia luk. W przypadku generowania z Flow do TypeScripta, te luki już nie występują (a w kodzie źródłowym korzystamy z dodatkowej walidacji typów Flow dla kodu wieloplatformowego).

import {Dimensions} from 'react-native';

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

Inne zmiany łamiące

Zapoznaj się z naszym dedykowanym przewodnikiem w dokumentacji, który szczegółowo opisuje wszystkie łamiące zmiany typów oraz sposób aktualizacji kodu.

Wdrażanie

Rozumiemy, że każda zmiana łamiąca w React Native będzie wymagała czasu od deweloperów na aktualizację w ich aplikacjach.

Teraz — Premiera opcji opt-in (0.80)

Opcja "react-native-strict-api" jest stabilna w wydaniu 0.80.

• To migracja jednorazowa. Chcemy, aby aplikacje i biblioteki włączały tę opcję we własnym tempie przez kilka kolejnych wydań.

• W obu trybach nic nie zmieni się w działaniu twojej aplikacji — to wpływa tylko na analizę TypeScripta.

• Oraz będziemy zbierać informacje zwrotne na temat brakujących interfejsów API za pośrednictwem naszego dedykowanego wątku.

Zalecane

Strict TypeScript API stanie się naszym domyślnym API w przyszłości.

Jeśli masz czas, warto przetestować opcję opt-in teraz w twoim tsconfig.json, aby zabezpieczyć swoją aplikację lub bibliotekę na przyszłość. To natychmiastowo sprawdzi, czy w twojej aplikacji pod wpływem Strict API pojawią się błędy typów. Może się okazać, że nie będzie żadnych(!) — w takim przypadku możesz śmiało kontynuować.

Przyszłość — Strict TypeScript API domyślnie

W przyszłości wymusimy, aby wszystkie bazy kodu używały naszego Strict API, i usuniemy starsze typy.

Termin tego będzie zależał od informacji zwrotnej od społeczności. Przez co najmniej dwa kolejne wydania React Native, Strict API pozostanie opcją do włączenia.

Często zadawane pytania

I'm using subpath imports today. What should I do?

Please migrate to the root 'react-native' import path.

• Subpath imports (e.g. 'react-native/Libraries/Alert/Alert') are becoming private APIs. Without preventing access to implementation files inside React Native, we can’t offer a stable JavaScript API.
• We want our deprecation warnings to motivate community feedback, which can be raised via our centralized discussion thread, if you believe we are not exposing code paths that are crucial for your app. Where justified, we may promote APIs to the index export.

I'm a library maintainer. How does this change impact me?

Both apps and libraries can opt in at their own pace, since tsconfig.json will only affect the immediate codebase.

• Typically, node_modules is excluded from validation by the TypeScript server in a React Native project. Therefore, your package's exported type definitions are the source of truth.

💡 We want feedback! As with changed subpath imports, if you encounter any integration issues with the Strict API, please let us know on GitHub.

Does this guarantee a final API for React Native yet?

Sadly, not yet. In 0.80, we've made a tooling investment so that React Native's existing JS API baseline can be accurately consumed via TypeScript — enabling future stable changes. We're formalizing the existing API you know and love.

In the future, we will take action to finalise the APIs we currently offer in core — across each language surface. API changes will be communicated via RFCs/announcements, and typically a deprecation cycle.

Why isn't React Native written in TypeScript?

React Native is core infrastructure at Meta. We test every merged change across our Family of Apps, before they hit general open source availability.

At this scale and sensitivity, correctness matters. The bottom line is that Flow offers us greater performance and greater strictness than TypeScript, including specific multi-platform support for React Native.

Podziękowania

Te zmiany były możliwe dzięki Iwo Plaza, Jakub Piasecki, Dawid Małecki, Alex Hunt oraz Riccardo Cipolleschi.

Podziękowania również dla Pietera Vanderwerffa, Rubéna Norte i Roba Hogana za dodatkową pomoc i wkład.

Learn more

Watch the talk!We shared a deep dive into our motivations and the work behind the Strict TypeScript API at App.js 2025.

View on YouTube