Updating Native Modules Documentation

docs/native-modules-intro.md

@@ -0,0 +1,25 @@
+---
+id: native-modules-intro
+title: Native Modules Intro
+---
+
+Sometimes a React Native app needs to access a native platform API that is not available by default in Javascript, for example the native APIs to access Apple or Android pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing.
+
+The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself!
+
+## Native Module Setup
+
+There are two ways to write a native module for your React Native application:
+
+1. Directly within your React Native application’s iOS/Android projects
+2. As a NPM package that can be installed as a dependency by your/other React Native applications
+
+This guide will first walk you through implementing a native module directly within a React Native application. However the native module you build in the following guide can be distributed as an NPM package. Check out the [Setting Up a Native Module as a NPM Package](native-modules-setup) guide if you are interested in doing so.
+
+## Getting Started
+
+In the following sections we will walk you through guides on how to build a native module directly within a React Native application. As a prerequisite, you will need a React Native application to work within. You can follow the steps [here](environment-setup) to setup a React Native application if you do not already have one.
+
+Imagine that you want to access the iOS/Android native calendar APIs from Javascript within a React Native application in order to create calendar events. React Native does not expose a Javascript API to communicate with the native calendar libraries. However, through native modules, you can write native code that communicates with native calendar APIs. Then you can invoke that native code through Javascript in your React Native application.
+
+In the following sections you will create such a Calendar native module for both [Android](native-modules-android) and [iOS](native-modules-ios).

website/i18n/en.json

@@ -221,6 +221,9 @@
       "native-modules-android": {
         "title": "Native Modules"
       },
+      "native-modules-intro": {
+        "title": "Native Modules Intro"
+      },
       "native-modules-ios": {
         "title": "Native Modules"
       },
@@ -2297,6 +2300,9 @@
       "version-0.5/version-0.5-native-modules-android": {
         "title": "Native Modules"
       },
+      "version-0.5/version-0.5-native-modules-intro": {
+        "title": "Native Modules Intro"
+      },
       "version-0.5/version-0.5-native-modules-ios": {
         "title": "Native Modules"
       },
@@ -4035,13 +4041,16 @@
         "title": "Native UI Components"
       },
       "version-0.63/version-0.63-native-modules-android": {
-        "title": "Native Modules"
+        "title": "Android Native Modules"
+      },
+      "version-0.63/version-0.63-native-modules-intro": {
+        "title": "Native Modules Intro"
       },
       "version-0.63/version-0.63-native-modules-ios": {
-        "title": "Native Modules"
+        "title": "iOS Native Modules"
       },
       "version-0.63/version-0.63-native-modules-setup": {
-        "title": "Native Modules Setup"
+        "title": "Native Modules NPM Package Setup"
       },
       "version-0.63/version-0.63-navigation": {
         "title": "Navigating Between Screens"

website/sidebars.json

@@ -46,18 +46,19 @@
     "JavaScript Runtime": ["javascript-environment", "timers", "hermes"],
     "Connectivity": ["network", "security"],
     "Native Components and Modules": [
+      "native-modules-intro",
+      "native-modules-android",
+      "native-modules-ios",
       "native-modules-setup",
       "direct-manipulation"
     ],
     "Guides (Android)": [
-      "native-modules-android",
       "native-components-android",
       "headless-js-android",
       "signed-apk-android",
       "removing-default-permissions"
     ],
     "Guides (iOS)": [
-      "native-modules-ios",
       "native-components-ios",
       "linking-libraries-ios",
       "running-on-simulator-ios",

website/versioned_docs/version-0.5/native-modules-intro.md

@@ -0,0 +1,26 @@
+---
+id: version-0.5-native-modules-intro
+title: Native Modules Intro
+original_id: native-modules-intro
+---
+
+Sometimes a React Native app needs to access a native platform API that is not available by default in Javascript, for example the native APIs to access Apple or Android pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing.
+
+The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself!
+
+## Native Module Setup
+
+There are two ways to write a native module for your React Native application:
+
+1. Directly within your React Native application’s iOS/Android projects
+2. As a NPM package that can be installed as a dependency by your/other React Native applications
+
+This guide will first walk you through implementing a native module directly within a React Native application. However the native module you build in the following guide can be distributed as an NPM package. Check out the [Setting Up a Native Module as a NPM Package](native-modules-setup) guide if you are interested in doing so.
+
+## Getting Started
+
+In the following sections we will walk you through guides on how to build a native module directly within a React Native application. As a prerequisite, you will need a React Native application to work within. You can follow the steps [here](environment-setup) to setup a React Native application if you do not already have one.
+
+Imagine that you want to access the iOS/Android native calendar APIs from Javascript within a React Native application in order to create calendar events. React Native does not expose a Javascript API to communicate with the native calendar libraries. However, through native modules, you can write native code that communicates with native calendar APIs. Then you can invoke that native code through Javascript in your React Native application.
+
+In the following sections you will create such a Calendar native module for both [Android](native-modules-android) and [iOS](native-modules-ios).