Restructuring React Native's Public API

[lunaleaps]

Note

Looking for feedback on this proposal! A lot of this thinking came from trying to enforce type consistency between our Flow and TS types which highlighted a lot of the problems we list below.

Some open questions:

• Thoughts about non-JS APIs, like ReactInstanceManager, how should we handle those? Why aren't those part of our docs?

Background

React Native currently defines its API via index.js. However index.js doesn’t fully capture the API that users interact with. Complex arguments (e.g. component props, events emitted) and types are not first class citizens of our public API.

This leads to users reaching into “internal files” for types and to understand React Native’s interface and concepts.

Example of products reaching in for types

import type {LayoutEvent} from 'react-native/Libraries/Types/CoreEventTypes';
import type {RootTag} from 'react-native/Libraries/Types/RootTagTypes';
import deepDiffer from 'react-native/Libraries/Utilities/differ/deepDiffer';

Problems

• Missing boundaries for public vs private APIs
  • Hard to detect when changes to the public API are made
    • Changes to TimingAnimationConfig would be a change to our public API
    • But TimingAnimation are not
  • Impacts
    • Anytime we need to know our public API has changed
      • TypeScript maintenance
      • Docs maintenance
• Docs don’t tell whole story of React Native public API and have unclear structure
  • E.g. processColor, the “objects”, “props” sections
• Lack of intentional structure in repository
  • Ambiguity around how to split up code and where to place it, when does something become a module?
  • No rules to set guidelines, automation around expectations of our API
• Android, iOS code is co-located with JS
  • Poor developer experience around using editors not configured to handle native code

Proposal

• Let’s structurally define what our public API is by creating a public folder
• Export types as part of our public API, as TS already does
• Set practices on where to place modules and single responsibility
  • e.g. One module per public type, or is that too cluttered?
  • What we're trying to avoid: CoreEventTypes has unclear rules about what belongs and hides types
• Use this opportunity to define the API we want
  • Create a deprecated folder to clearly delineate

Proposed Code Structure

• .js.flow suffix indicates a type-only file
• For each file under public/, should have a parallel .d.ts
• Every subfolder under public should correspond to documentation
• __tests__ folder exist under both public and private

...
js/
   index.js
   public/
       deprecated/
          PointPropType.js.flow
          ProgressView.js
          PushNotificationIOS.js
       …
       Alert/
          __tests__/
          Alert.js
          Alert.d.ts
       Text/
          __tests__/
          TextInput.js
          TextInput.d.ts
          TextInputProps.js.flow
          TextInputProps.d.ts
          TextStyle.js.flow
          TextStyle.d.ts
       LayoutEvent/
          Layout.js.flow
          Layout.d.ts
       PointerEvent/
          PointerEvent.js.flow
          PointerEvent.d.ts
       PressEvent/
          PressEvent.js.flow
          PressEvent.d.ts
       Animated/
          __tests__/
          TimingConfig.js.flow
          TimingConfig.d.ts
          Animated.js
          Animated.d.ts
          AnimatedProps.js.flow
          AnimatedProps.d.ts
       StyleSheet/
          __tests__/
          StyleSheet.js
          StyleSheet.d.ts
       PlatformColor/
          PlatformColorValueTypes.js.flow
          PlatformColorValueTypes.d.ts
       processColor/
          processColor.js
          processColor.d.ts
       Image/
          ImageStyle.js.flow
          ImageStyle.d.ts
          Image.ios.js
          Image.android.js
          Image.d.ts
       Pressable/…
       Pressability/…
       View/
          ViewStyle.js.flow
          ViewStyle.d.ts
          ViewProps.js.flow
          ViewProps.d.ts
          View.js
          View.d.ts
       …          
          
   private/
       Alert/
          NativeAlertManager.js
          RCTAlertManager.android.js
          RCTAlertManager.ios.js
       Text/
          __tests__/
          TextInputState.js
       Animated/
          animation/
              TimingAnimation.js
              SpringAnimation.js
           

Proposed Documentation structure

Our current doc structure

If we want our documentation and public folder to mirror one another, our docs will also need re-structuring and additions of missing types. Proposing:

• Stop separating between “Components” and “APIs”. Both are APIs, some are just views
  • We can always signify if something is a React component with an indicator
  • Taking inspiration from Android documentation
• Remove “Props” section
  • "Layout Props" should probably be part of View style props?
  • Style props specific to a component should be grouped with the component documentation
    • E.g. View documentation will have types for props and styles of View
  • Shadow props should be moved under View docs
• Remove “Objects” section
  • Event types will be documented as first class API

// index.js
// The only things we export from index.js are under public folder

import type {TextInputProps} from './public/Text/TextInputProps';
import type {TimingConfig} from './public/Animation/TimingConfig';
import type {MouseEvent} from './public/ViewEvents/MouseEvent';

export type {TextInputProps, TimingConfig, MouseEvent};

module.exports = {
   get TextInput() {
      return require('.public/Text/TextInput');
   },
};

Approach

Will this be a breaking change?

Eventually yes. We would want people to stop reaching in react-native library and move to imports from index.js

For a gradual migration strategy, we can continue to keep our existing repo structure and curate our public APIs and have them point to current implementation locations.

E.g. js/public/Text/TextInputProps.js.flow

import {Props} from '../../../Libraries/Components/TextInput';
export type {Props as TextInputProps};

For the breaking change release version, we can then move internal implementations under private/.

Future

• With new structure of repo, we could generate index.js
• Ability to create a bundle that excludes deprecated folder for apps that don’t use any deprecated components
  E.g. index.deprecated.js

import type {TextInputProps, TimingConfig, MouseEvent} from './index';
export type {TextInputProps, TimingConfig, MouseEvent};
const index = require('./index');

module.exports = {
   …index,
   get ProgressView() {
      return require('.public/deprecated/ProgressView');
   },
};

[tido64]

Have you considered using exports map for this? As I understand it, it would allow you to name exports without having to change the underlying file structure, and users will get errors when they try to import anything that isn't explicitly exported. For example:

{
  "exports": {
    ".": "./index.js",
    "./Libraries/Components/Text": "./Libraries/Components/TextInput/TextInput.js",
  }
}

// Error
import type {TextInputProps} from 'react-native/Libraries/Components/TextInput/TextInput';

// Works
import type {TextInputProps} from 'react-native/Libraries/Components/Text';

I think TypeScript should support it. Not sure about Flow. Metro is also adding support for it: facebook/metro#670

[lunaleaps]

I think exports map makes sense in a way to clarify what we export! We could really list out everything that we actually intend the user to import. If those modules could provide the boundaries of our API, that's what I'm mainly concerned about

[slorber]

Not exactly the same use-case but for Docusaurus we added public vs internal export entrypoints on some packages:

https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/package.json#L11

  "exports": {
    ".": "./lib/index.js",
    "./internal": "./lib/internal.js",
  },

This works great to prevent bad internal API usage. And we also get some user feedback (users complaining) when an internal API is not exposed anymore, which allows a better understanding of who uses what API and why, with the ability to suggest an alternative.

Something to consider: how do you plan to move an API from internal to public? => it's likely you'll want the newly public API to remain in the internal entrypoint for retrocompatibility.

[lunaleaps]

Hm for a move from internal to public, I'd imagine similar to deprecating a component. With one release being a buffer for people for folks to migrate off. I think it'd mostly be a matter of communication, or am I missing something?

[lunaleaps]

Regarding exports, @huntie is actively working on this. We should definitely follow up once that work is up!

[huntie]

Thanks Luna!

• The "exports" RFC is now shared for discussion here (RFC: Metro package exports support #534). A few changes incoming, but we will absolutely support the above capabilities.
• Progress updates will be added here (Feature: support new package.json exports field facebook/metro#670) when work kicks off.
• Since Metro ships with React Native, we should be able to launch this in one go in a future React Native major release. (Alternative bundlers such as Webpack should have full support already.)

[rubennorte]

Thanks for working on this, @lunaleaps!

I agree with the problem statement and I think improving the directory structure with a better convention is a good idea, but I'm not sure it's the best solution for that problem. Take these 2 problems:

• Hard to detect when changes to the public API are made
• Anytime we need to know our public API has changed [...] TypeScript maintenance. Docs maintenance.

Having a directory structure to convey whether an API is public or private depends too much on human intervention. I think it'll be easier for certain private types/values to leak into public space, and also easy for certain public types/values to stay public for longer than necessary. You can't avoid imports from public to private, so there's always a chance that you ends up exposing something private indirectly through type definitions.

I think automation could do this more efficiently instead. For example, we could have a build step that, from all the exports in index.js, recursively tracked all exported types and values, and dumped them into an index.js.flow file. We could use that file to 1) detect changes to the public API and 2) autogenerate all typescript definitions.

[rubennorte]

I did a quick search and found this for TypeScript, which is similar to what I was suggesting: https://api-extractor.com/

We can't use it directly (because it's for TS) but I think we can build a simpler version of that for Flow.

[lunaleaps]

I think this is the ideal solution -- would this approach be different than our ask to the Flow team of generating a declaration for React Native?

[rubennorte]

I don't have the details about that request to the Flow team, but I think this is something that Flow could provide (and it'd be the right place to implement it).

[rickhanlonii]

+1 to the recommendation to use exports instead of changing the directory structure.

Another thing we could consider is using Rollup to build a flat bundle and only publish that bundle instead of the source code. Then you could only import what's exported.

[rubennorte]

Another thing we could consider is using Rollup to build a flat bundle and only publish that bundle instead of the source code. Then you could only import what's exported.

I'm not sure that would be a good idea because I think it'd invalidate inline requires, and the react-native package is pretty big. Probably worth investigating though.

[lunaleaps]

I agree we maybe don't need to change the entire structure of directory -- although I'd still push for some re-organizing of our API and if anything I think this proposal is about defining what is our public API which maybe documentation is the best way to convey that?

[rickhanlonii]

@rubennorte good point, would the concern there mainly be native modules/components? The core infra stuff is / should be eagerly required, or in practice required first anyway, right? What would you think about multiple flat files?

[rubennorte]

@rickhanlonii native modules/components are a big part of it, but not only that. The surface area in React Native is pretty big and there are many parts of the library that apps might not use at all. For example, if you don't use FlatList/VirtualizedList you don't need to evaluate the whole module and its dependencies. For things we know for sure will be evaluated we could combine them, but I don't think doing this in a case-by-case basis is useful.

[cortinico]

Happy to see those kind of proposals!

However index.js doesn’t fully capture the API that users interact with

Adding to this, beside index.js we don't have any visibility of our API surface on:

• JVM Apis (Java/Kotlin public function that user can call into)
• Objc Apis (Similary to Java/Kotlin, methods that the user can call in their platform code on iOS).
• C++ Headers (essentially everyone can import everything from within React Native and start using it).
• Build logic flags/APIs (i.e. if we remove/rename a build flag we'll break the build phase for everyone. We never monitor those kind of changes).

I don't want to make this proposal grow too much, but I believe we should follow an holistic approach and define 'what the public API is' regardless of the platform.

Similarly to JS, we can have a .public package in Java and limit visibility to only class contained there. There are tools to track and limit the visibility of those APIs (japicmp, binary-compatibility-validator).

For C++, we could use forward headers (which we don't use nearly at all) to scope the visibility of our code.

Android, iOS code is co-located with JS
Poor developer experience around using editors not configured to handle native code

Thanks for pointing this out. We recently fixed a major IDE incompatibility with the New Architecture due to C++ code being co-located with the Java/Kotlin code. As a rule of thumb, I'd try to stick to keeping the project layout that the platform provide (till we eventually device to depart from the platform build system, if ever).

[lunaleaps]

Thanks for sharing! I agree we need a holistic public API. @arati-1 and I are going to work on restructuring the JS documentation and I think it's a great opportunity to add our native APIs as well -- let's talk :)