Skip to content

Commit 401adaf

Browse files
huntiehuntie
authored
[docs] Add user guide for the Strict TypeScript API (0.80) (facebook#4628)
1 parent 2ff5c7a commit 401adaf

File tree

2 files changed

+192
-0
lines changed

2 files changed

+192
-0
lines changed

‎docs/strict-typescript-api.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
id: strict-typescript-api
3+
title: Strict TypeScript API (opt in)
4+
---
5+
6+
The Strict TypeScript API is a preview of our future, stable JavaScript API for React Native.
7+
8+
Specifically, this is a new set of TypeScript types for the `react-native` npm package, available from 0.80 onwards. These provide stronger and more futureproof type accuracy, and will allow us to confidently evolve React Native's API into a stable shape. Opting in to the Strict TypeScript API brings some structural type differences, and is therefore a one-time breaking change.
9+
10+
The new types are:
11+
12+
1. **Generated directly from our source code** — improving coverage and correctness, so you can expect stronger compatibility guarantees.
13+
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.
14+
15+
When the community is ready, the Strict TypeScript API will become our default API in future — synchronized with deep imports removal.
16+
17+
## Opting in
18+
19+
We're shipping these new types alongside our existing types, meaning you can choose to migrate when ready. We encourage early adopters and newly created apps to opt in via your `tsconfig.json` file.
20+
21+
Opting in is a **breaking change**, since some of our new types have updated names and shapes, although many apps won't be affected. You can learn about each breaking change in the next section.
22+
23+
```json title="tsconfig.json"
24+
{
25+
"extends": "@react-native/typescript-config",
26+
"compilerOptions": {
27+
...
28+
"customConditions": ["react-native-strict-api"]
29+
}
30+
}
31+
```
32+
33+
:::note Under the hood
34+
35+
This will instruct TypeScript to resolve `react-native` types from our new [`types_generated/`](https://www.npmjs.com/package/react-native?activeTab=code) dir, instead of the previous [`types/`](https://www.npmjs.com/package/react-native?activeTab=code) dir (manually maintained). No restart of TypeScript or your text editor is required.
36+
37+
:::
38+
39+
The Strict TypeScript API follows our [RFC](https://github.com/react-native-community/discussions-and-proposals/pull/894) to remove deep imports from React Native. Therefore, some APIs are no longer exported at root. This is intentional, in order to reduce the overall surface area of React Native's API.
40+
41+
:::tip API feedback
42+
43+
**Sending feedback**: We will be working with the community to finalize which APIs we export over (at least) the next two React Native releases. Please share your feedback in our [feedback thread](https://github.com/react-native-community/discussions-and-proposals/discussions/893).
44+
45+
See also our announcement blog post (incoming) for more info on our motivation and timelines.
46+
47+
:::
48+
49+
## Migration guide
50+
51+
### Codegen types should now be imported from the `react-native` package
52+
53+
Types used for codegen, like `Int32`, `Double`, `WithDefault` etc. are now available under a single `CodegenTypes` namespace. Similarly, `codegenNativeComponent` and `codegenNativeCommands` are now available to import from the react-native package instead of using the deep import.
54+
55+
Namespaced `CodegenTypes` as well as `codegenNativeCommands` and `codegenNativeComponent` are also available from `react-native` package when the Strict API is not enabled to make the adoption easier for third-party libraries.
56+
57+
**Before**
58+
59+
```ts title=""
60+
import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
61+
import type {
62+
Int32,
63+
WithDefault,
64+
} from 'react-native/Libraries/Types/CodegenTypes';
65+
66+
interface NativeProps extends ViewProps {
67+
enabled?: WithDefault<boolean, true>;
68+
size?: Int32;
69+
}
70+
71+
export default codegenNativeComponent<NativeProps>(
72+
'RNCustomComponent',
73+
);
74+
```
75+
76+
**After**
77+
78+
```ts title=""
79+
import {CodegenTypes, codegenNativeComponent} from 'react-native';
80+
81+
interface NativeProps extends ViewProps {
82+
enabled?: CodegenTypes.WithDefault<boolean, true>;
83+
size?: CodegenTypes.Int32;
84+
}
85+
86+
export default codegenNativeComponent<NativeProps>(
87+
'RNCustomComponent',
88+
);
89+
```
90+
91+
### Removal of `*Static` types
92+
93+
**Before**
94+
95+
```tsx title=""
96+
import {Linking, LinkingStatic} from 'react-native';
97+
98+
function foo(linking: LinkingStatic) {}
99+
foo(Linking);
100+
```
101+
102+
**After**
103+
104+
```tsx title=""
105+
import {Linking} from 'react-native';
106+
107+
function foo(linking: Linking) {}
108+
foo(Linking);
109+
```
110+
111+
The following APIs were previously named as `*Static` plus a variable declaration of said type. In most cases there was an alias so that value and the type were exported under the same identifier, but some were missing.
112+
113+
(For example there was an `AlertStatic` type, `Alert` variable of type `AlertStatic` and type `Alert` which was an alias for `AlertStatic`. But in the case of `PixelRatio` there was a `PixelRatioStatic` type and a `PixelRatio` variable of that type without additional type aliases.)
114+
115+
**Affected APIs**
116+
117+
- `AlertStatic`
118+
- `ActionSheetIOSStatic`
119+
- `ToastAndroidStatic`
120+
- `InteractionManagerStatic` (In this case there was no relevant `InteractionManager` type alias)
121+
- `UIManagerStatic`
122+
- `PlatformStatic`
123+
- `SectionListStatic`
124+
- `PixelRatioStatic` (In this case there was no relevant `PixelRatio` type alias)
125+
- `AppStateStatic`
126+
- `AccessibilityInfoStatic`
127+
- `ImageResizeModeStatic`
128+
- `BackHandlerStatic`
129+
- `DevMenuStatic` (In this case there was no relevant `DevMenu` type alias)
130+
- `ClipboardStatic`
131+
- `PermissionsAndroidStatic`
132+
- `ShareStatic`
133+
- `DeviceEventEmitterStatic`
134+
- `LayoutAnimationStatic`
135+
- `KeyboardStatic` (In this case there was no relevant `Keyboard` type alias)
136+
- `DevSettingsStatic` (In this case there was no relevant `DevSettings` type alias)
137+
- `I18nManagerStatic`
138+
- `EasingStatic`
139+
- `PanResponderStatic`
140+
- `NativeModulesStatic` (In this case there was no relevant `NativeModules` type alias)
141+
- `LogBoxStatic`
142+
- `PushNotificationIOSStatic`
143+
- `SettingsStatic`
144+
- `VibrationStatic`
145+
146+
### Some core components are now function components instead of class components
147+
148+
- `View`
149+
- `Image`
150+
- `TextInput`
151+
- `Modal`
152+
- `Text`
153+
- `TouchableWithoutFeedback`
154+
- `Switch`
155+
- `ActivityIndicator`
156+
- `ProgressBarAndroid`
157+
- `InputAccessoryView`
158+
- `Button`
159+
- `SafeAreaView`
160+
161+
Due to this change, accessing ref types of these views requires using `React.ComponentRef<typeof View>` pattern which works as expected for both class and function components, e.g.:
162+
163+
```ts title=""
164+
const ref = useRef<React.ComponentRef<typeof View>>(null);
165+
```
166+
167+
## Other breaking changes
168+
169+
### Changes to Animated types
170+
171+
Animated nodes were previously generic types based on their interpolation output. Now, they are non-generic types with a generic `interpolate` method.
172+
173+
`Animated.LegacyRef` is no longer available.
174+
175+
### Unified types for optional props
176+
177+
In the new types, every optional prop will be typed as `type | undefined`.
178+
179+
### Removal of some deprecated types
180+
181+
All types listed in [`DeprecatedPropertiesAlias.d.ts`](https://github.com/facebook/react-native/blob/0.80-stable/packages/react-native/types/public/DeprecatedPropertiesAlias.d.ts) are inaccessible under the Strict API.
182+
183+
### Removal of leftover component props
184+
185+
Some properties that were defined in type definitions but were not used by the component or were lacking a definition were removed (for example: `lineBreakMode` on `Text`, `scrollWithoutAnimationTo` on `ScrollView`, transform styles defined outside of transform array).
186+
187+
### Previously accessible private type helpers may now be removed
188+
189+
Due to the configuration of the previous type definitions, every defined type was accessible from the `react-native` package. This included types that were not explicitly exported and helper types that were only supposed to be used internally.
190+
191+
Notable examples of this are types related to StyleSheet (like `RecursiveArray`, `RegisteredStyle` and `Falsy`) and Animated (like `WithAnimatedArray` and `WithAnimatedObject`).

‎website/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ export default {
2727
'metro',
2828
'libraries',
2929
'typescript',
30+
'strict-typescript-api',
3031
'upgrading',
3132
],
3233
'UI & Interaction': [

0 commit comments

Comments
 (0)