add docs for react-native-screens (react-navigation#407)

Author: jarvisluong

docs/limitations.md

@@ -57,6 +57,6 @@ We are able to offload animations to another thread using React Native's [Animat
 
 Some platform-specific behavior either cannot be implemented or has not yet been implemented in React Navigation.
 
-Versions prior to 2.14.0 do not support the ["reachability feature" on iOS](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/). When you toggle this feature, the app moves down towards the bottom of the screen so you can easily reach the navigation bar and other functionality near the top of the UI. When you navigate to another screen using the built-in iOS navigation API, the UI will jump back up to the top of the screen. React-navigation 2.14.0 and later supports this feature through integration with [react-native-screens](https://github.com/kmagiera/react-native-screens).
+Versions prior to 2.14.0 do not support the ["reachability feature" on iOS](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/). When you toggle this feature, the app moves down towards the bottom of the screen so you can easily reach the navigation bar and other functionality near the top of the UI. When you navigate to another screen using the built-in iOS navigation API, the UI will jump back up to the top of the screen. React-navigation 2.14.0 and later supports this feature through integration with [react-native-screens](react-native-screens.html).
 
 React-navigation does not include support for the peek & pop feature available on devices with 3D touch.

docs/react-native-screens.md

@@ -0,0 +1,25 @@
+---
+id: react-native-screens
+title: Optimize memory usage and performance
+sidebar_label: Optimize memory usage and performance
+---
+
+Prior to `react-navigation@2.14.0`, all screens are essentially regular native `View` in each platform, which will increase memory usage and make the render tree deep in a heavy-stacked application. This is one of the reason your app is slowing down comparing to native navigation solution.
+
+With the advent of `react-native-screens`, the native screen optimization is brought possible to `react-navigation` by bringing the native navigation component (`UIViewController` for iOS, and `FragmentActivity` for Android). By using `react-native-screens`, it is possible for each native platform to optimize the memory usage for screens that are under the view stack and also simplify the native node hierarchy. You can take a look at the comparison [here](https://twitter.com/janicduplessis/status/1039979591815897088?s=21) to see the performance gain.
+
+## Setup when you are using Expo
+
+By default expo already included `react-native-screens`, all you need to do is pasting the following snippet before your navigation stacks are rendered (typically in an `index.js` or `App.js` file):
+
+```js
+// Before rendering any navigation stack
+import { useScreens } from 'react-native-screens';
+useScreens();
+```
+
+## Setup in normal react-native applications
+
+You will need to follow the installation instruction from [react-native-screens](https://github.com/kmagiera/react-native-screens) first. After that, you can import the library like mentioned above and enjoy the optimization.
+
+

website/i18n/en.json

@@ -212,6 +212,10 @@
         "title": "Pitch & anti-pitch",
         "sidebar_label": "Pitch & anti-pitch"
       },
+      "react-native-screens": {
+        "title": "Optimize memory usage and performance",
+        "sidebar_label": "Optimize memory usage and performance"
+      },
       "redux-integration": {
         "title": "Redux integration",
         "sidebar_label": "Redux integration"
@@ -606,6 +610,10 @@
         "title": "Passing parameters to routes",
         "sidebar_label": "Passing parameters to routes"
       },
+      "version-2.x-react-native-screens": {
+        "title": "Optimize memory usage and performance",
+        "sidebar_label": "Optimize memory usage and performance"
+      },
       "version-2.x-redux-integration": {
         "title": "Redux integration",
         "sidebar_label": "Redux integration"
@@ -758,6 +766,10 @@
         "title": "Passing parameters to routes",
         "sidebar_label": "Passing parameters to routes"
       },
+      "version-3.x-react-native-screens": {
+        "title": "Optimize memory usage and performance",
+        "sidebar_label": "Optimize memory usage and performance"
+      },
       "version-3.x-redux-integration": {
         "title": "Redux integration",
         "sidebar_label": "Redux integration"

website/sidebars.json

@@ -13,6 +13,7 @@
       "next-steps",
       "glossary-of-terms",
       "common-mistakes",
+      "react-native-screens",
       "limitations"
     ],
     "Guides": [

website/versioned_docs/version-2.x/limitations.md

@@ -56,6 +56,6 @@ We are able to offload animations to another thread using React Native's [Animat
 
 Some platform-specific behavior either cannot be implemented or has not yet been implemented in React Navigation.
 
-Versions prior to 2.14.0 do not support the ["reachability feature" on iOS](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/). When you toggle this feature, the app moves down towards the bottom of the screen so you can easily reach the navigation bar and other functionality near the top of the UI. When you navigate to another screen using the built-in iOS navigation API, the UI will jump back up to the top of the screen. React-navigation 2.14.0 and later supports this feature through integration with [react-native-screens](https://github.com/kmagiera/react-native-screens).
+Versions prior to 2.14.0 do not support the ["reachability feature" on iOS](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/). When you toggle this feature, the app moves down towards the bottom of the screen so you can easily reach the navigation bar and other functionality near the top of the UI. When you navigate to another screen using the built-in iOS navigation API, the UI will jump back up to the top of the screen. React-navigation 2.14.0 and later supports this feature through integration with [react-native-screens](react-native-screens.html).
 
 React-navigation does not include support for the peek & pop feature available on devices with 3D touch.

website/versioned_docs/version-2.x/react-native-screens.md

@@ -0,0 +1,26 @@
+---
+id: version-2.x-react-native-screens
+title: Optimize memory usage and performance
+sidebar_label: Optimize memory usage and performance
+original_id: react-native-screens
+---
+
+Prior to `react-navigation@2.14.0`, all screens are essentially regular native `View` in each platform, which will increase memory usage and make the render tree deep in a heavy-stacked application. This is one of the reason your app is slowing down comparing to native navigation solution.
+
+With the advent of `react-native-screens`, the native screen optimization is brought possible to `react-navigation` by bringing the native navigation component (`UIViewController` for iOS, and `FragmentActivity` for Android). By using `react-native-screens`, it is possible for each native platform to optimize the memory usage for screens that are under the view stack and also simplify the native node hierarchy. You can take a look at the comparison [here](https://twitter.com/janicduplessis/status/1039979591815897088?s=21) to see the performance gain.
+
+## Setup when you are using Expo
+
+By default expo already included `react-native-screens`, all you need to do is pasting the following snippet before your navigation stacks are rendered (typically in an `index.js` or `App.js` file):
+
+```js
+// Before rendering any navigation stack
+import { useScreens } from 'react-native-screens';
+useScreens();
+```
+
+## Setup in normal react-native applications
+
+You will need to follow the installation instruction from [react-native-screens](https://github.com/kmagiera/react-native-screens) first. After that, you can import the library like mentioned above and enjoy the optimization.
+
+

website/versioned_docs/version-3.x/limitations.md

@@ -58,6 +58,6 @@ We are able to offload animations to another thread using React Native's [Animat
 
 Some platform-specific behavior either cannot be implemented or has not yet been implemented in React Navigation.
 
-Versions prior to 2.14.0 do not support the ["reachability feature" on iOS](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/). When you toggle this feature, the app moves down towards the bottom of the screen so you can easily reach the navigation bar and other functionality near the top of the UI. When you navigate to another screen using the built-in iOS navigation API, the UI will jump back up to the top of the screen. React-navigation 2.14.0 and later supports this feature through integration with [react-native-screens](https://github.com/kmagiera/react-native-screens).
+Versions prior to 2.14.0 do not support the ["reachability feature" on iOS](https://www.cnet.com/how-to/how-to-use-reachability-on-iphone-6-6-plus/). When you toggle this feature, the app moves down towards the bottom of the screen so you can easily reach the navigation bar and other functionality near the top of the UI. When you navigate to another screen using the built-in iOS navigation API, the UI will jump back up to the top of the screen. React-navigation 2.14.0 and later supports this feature through integration with [react-native-screens](react-native-screens.html).
 
 React-navigation does not include support for the peek & pop feature available on devices with 3D touch.

website/versioned_docs/version-3.x/react-native-screens.md

@@ -0,0 +1,26 @@
+---
+id: version-3.x-react-native-screens
+title: Optimize memory usage and performance
+sidebar_label: Optimize memory usage and performance
+original_id: react-native-screens
+---
+
+Prior to `react-navigation@2.14.0`, all screens are essentially regular native `View` in each platform, which will increase memory usage and make the render tree deep in a heavy-stacked application. This is one of the reason your app is slowing down comparing to native navigation solution.
+
+With the advent of `react-native-screens`, the native screen optimization is brought possible to `react-navigation` by bringing the native navigation component (`UIViewController` for iOS, and `FragmentActivity` for Android). By using `react-native-screens`, it is possible for each native platform to optimize the memory usage for screens that are under the view stack and also simplify the native node hierarchy. You can take a look at the comparison [here](https://twitter.com/janicduplessis/status/1039979591815897088?s=21) to see the performance gain.
+
+## Setup when you are using Expo
+
+By default expo already included `react-native-screens`, all you need to do is pasting the following snippet before your navigation stacks are rendered (typically in an `index.js` or `App.js` file):
+
+```js
+// Before rendering any navigation stack
+import { useScreens } from 'react-native-screens';
+useScreens();
+```
+
+## Setup in normal react-native applications
+
+You will need to follow the installation instruction from [react-native-screens](https://github.com/kmagiera/react-native-screens) first. After that, you can import the library like mentioned above and enjoy the optimization.
+
+

website/versioned_sidebars/version-2.x-sidebars.json

@@ -12,6 +12,7 @@
       "version-2.x-next-steps",
       "version-2.x-glossary-of-terms",
       "version-2.x-common-mistakes",
+      "version-2.x-react-native-screens",
       "version-2.x-limitations"
     ],
     "Assorted Guides": [

website/versioned_sidebars/version-3.x-sidebars.json

@@ -13,6 +13,7 @@
       "version-3.x-next-steps",
       "version-3.x-glossary-of-terms",
       "version-3.x-common-mistakes",
+      "version-3.x-react-native-screens",
       "version-3.x-limitations"
     ],
     "Guides": [