Moving Towards a Stable JavaScript API (New Changes in 0.80)

In React Native 0.80, we’re introducing two significant changes to React Native’s JavaScript API — the deprecation of deep imports, and our new Strict TypeScript API. These are part of an ongoing effort to accurately define our API and offer dependable type safety to users and frameworks.

Quick takeaways:

• Deep imports deprecation: From 0.80, we’re introducing deprecation warnings for deep imports from the react-native package.
• Opt-in Strict TypeScript API: We are moving to from-source TypeScript types and a new public API baseline under TypeScript. These enable stronger and more futureproof type accuracy, and will be a one-time breaking change. Opt in via compilerOptions in your project’s tsconfig.json.
• We’ll work with the community over time to ensure that these changes work for everyone, before enabling the Strict TypeScript API by default in a future React Native release.

What’s changing and why​

We are moving to improve and stabilise React Native’s public JavaScript API — i.e. what you get when you import 'react-native'.

Historically, we’ve approximated this. React Native is authored in Flow, but the community has long since moved to TypeScript in open source, which is how the public API is consumed and validated for compatibility. Our types have been (lovingly) community-contributed, and since merged and aligned in our codebase. However, these have relied on manual maintenance and no automated tooling, introducing correctness gaps.

Additionally, our public JS API has been poorly defined in terms of module boundaries — e.g. internal 'react-native/Libraries/' deep imports were reachable by app code, but could frequently change as we updated these internals.

In 0.80, we’re addressing these issues by deprecating deep imports, and introducing a user opt-in to a new, generated API baseline in TypeScript. We’re calling this our Strict TypeScript API. Ultimately, this is the groundwork to offer a stable React Native API in future.

Deprecating deep imports from react-native​

The main change we’re making to our API today is deprecating the use of deep imports (RFC), with warnings in ESLint and the JS console. Deep imports of values and types should be updated to react-native‘s root import.

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

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

This change reduces the total surface area of our JavaScript API into a fixed set of exports which we can control and make stable in a future release. We’re targeting a removal of these import paths in 0.82.

Opting out

Please bear in mind that we aim to remove deep imports from React Native’s API in a future release, and these should instead be updated to the root import.

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

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

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

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

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

npx expo start --clear

Strict TypeScript API (opt-in)​

The Strict TypeScript API is a new set of TypeScript types in the react-native package, which can be opted into via your tsconfig.json. We’re shipping these alongside our existing TS types, meaning you can choose to migrate when ready.

The new types are:

1. Generated directly from our source code — improving coverage and correctness, so you can expect stronger compatibility guarantees.
2. Restricted to react-native‘s index file — more tightly defining our public API, and meaning we won’t break the API when making internal file changes.

When the community is ready, the Strict TypeScript API will become our default API in future — synchronized with deep imports removal. This means it’s a good idea to begin opting in, as you’ll be ready for React Native’s future stable JS API.

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

Breaking: Deep imports are disallowed​

As above, types under the Strict TypeScript API are now only resolvable from the main 'react-native' import path, enforcing package encapsulation, per our above deprecation.

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

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

Breaking: Some type names / shapes have changed​

Types are now generated from source, rather than manually maintained. In doing this:

• We’ve aligned differences that had built up from the community contributed types — and also increased the type coverage of our source code.
• We’ve intentionally updated some type names and type shapes, where there was scope to simplify or reduce ambiguity.

Example: Stricter exported symbols​

The Linking API is now a single interface, rather than two exports. This follows for a number of other APIs (see docs).

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

Example: Fixed / more complete types​

Previous manual type definitions left the opportunity for type gaps. Under generated Flow → TypeScript, these are no longer present (and at source, benefit from Flow’s additional type validation for multi-platform code).

import {Dimensions} from 'react-native';

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

Other breaking changes​

Please refer to our dedicated guide in the docs which details all breaking types changes and how to update your code.

Rollout​

We appreciate that any breaking change to React Native will take time for developers to update to in their apps.

Now — Opt-in launch (0.80)​

The "react-native-strict-api" opt-in is stable in the 0.80 release.

• This is a one-time migration. We aim for apps and libraries to opt in at their own pace over the next couple of releases.
• Under either mode, nothing will change for your app at runtime — this affects TypeScript analysis only.
• And, we will take feedback on missing APIs, via our dedicated feedback thread.

Future — Strict TypeScript API by default​

In the future, we will require all codebases to use our Strict API, and will remove the legacy types.

The timeline for this will be based on community feedback. For at least the next two React Native releases, the Strict API will remain an opt-in.

FAQs​

Thanks​

These changes were made possible by Iwo Plaza, Jakub Piasecki, Dawid Małecki, Alex Hunt, and Riccardo Cipolleschi.

Thanks also to Pieter Vanderwerff, Rubén Norte, and Rob Hogan for their additional help and input.

Source: Read More