From 3b39d7945983ff781f738795881b6b5f39ce53b1 Mon Sep 17 00:00:00 2001 From: Brent Vatne Date: Tue, 2 Apr 2024 22:03:27 -0700 Subject: [PATCH] [docs] "Existing React Native apps" and "Existing native apps" docs groups (#27608) Co-authored-by: Alan Hughes Co-authored-by: James Ide --- docs/common/error-utilities.ts | 3 + docs/constants/navigation.js | 21 +- .../{bare => archive}/using-expo-client.mdx | 0 .../pages/bare/install-dev-builds-in-bare.mdx | 50 +++-- docs/pages/bare/installing-expo-modules.mdx | 2 +- docs/pages/bare/installing-updates.mdx | 32 ++- docs/pages/bare/overview.mdx | 81 ++++---- .../brownfield/installing-expo-modules.mdx | 193 ++++++++++++++++++ docs/pages/brownfield/overview.mdx | 47 +++++ .../development-builds/create-a-build.mdx | 2 +- 10 files changed, 353 insertions(+), 78 deletions(-) rename docs/pages/{bare => archive}/using-expo-client.mdx (100%) create mode 100644 docs/pages/brownfield/installing-expo-modules.mdx create mode 100644 docs/pages/brownfield/overview.mdx diff --git a/docs/common/error-utilities.ts b/docs/common/error-utilities.ts index 0ef8aa9b61f27..6b2181d2cdaa6 100644 --- a/docs/common/error-utilities.ts +++ b/docs/common/error-utilities.ts @@ -446,4 +446,7 @@ const RENAMED_PAGES: Record = { // Deprecated Webpack support '/guides/customizing-webpack': '/archive/customizing-webpack', + + // Stop encouraging usage of Expo Go when using native modules + '/bare/using-expo-client': '/archive/using-expo-client', }; diff --git a/docs/constants/navigation.js b/docs/constants/navigation.js index baf1808bdeb71..a58f1b7ae121b 100644 --- a/docs/constants/navigation.js +++ b/docs/constants/navigation.js @@ -157,6 +157,18 @@ const general = [ ], { expanded: false } ), + makeSection('Existing React Native apps', [ + makePage('bare/overview.mdx'), + makePage('bare/installing-expo-modules.mdx'), + makePage('bare/using-expo-cli.mdx'), + makePage('bare/installing-updates.mdx'), + makePage('bare/install-dev-builds-in-bare.mdx'), + makePage('bare/upgrade.mdx'), + ]), + makeSection('Existing native apps', [ + makePage('brownfield/overview.mdx'), + makePage('brownfield/installing-expo-modules.mdx'), + ]), makeGroup( 'Reference', [ @@ -415,15 +427,6 @@ const general = [ makePage('accounts/working-together.mdx'), makePage('accounts/sso.mdx'), ]), - makeSection('Bare React Native', [ - makePage('bare/overview.mdx'), - makePage('bare/installing-expo-modules.mdx'), - makePage('bare/using-expo-cli.mdx'), - makePage('bare/installing-updates.mdx'), - makePage('bare/using-expo-client.mdx'), - makePage('bare/install-dev-builds-in-bare.mdx'), - makePage('bare/upgrade.mdx'), - ]), ], { expanded: true } ), diff --git a/docs/pages/bare/using-expo-client.mdx b/docs/pages/archive/using-expo-client.mdx similarity index 100% rename from docs/pages/bare/using-expo-client.mdx rename to docs/pages/archive/using-expo-client.mdx diff --git a/docs/pages/bare/install-dev-builds-in-bare.mdx b/docs/pages/bare/install-dev-builds-in-bare.mdx index e4adb42c32bbd..4c5317a224a3f 100644 --- a/docs/pages/bare/install-dev-builds-in-bare.mdx +++ b/docs/pages/bare/install-dev-builds-in-bare.mdx @@ -1,33 +1,37 @@ --- -title: Install development builds in bare React Native -sidebar_title: Install development builds in bare React Native -description: Learn how to configure development builds for bare React Native projects. +title: Install expo-dev-client in a bare React Native project +sidebar_title: Install expo-dev-client +description: Learn how to install and configure expo-dev-client in bare React Native projects. --- import { Terminal } from '~/ui/components/Snippet'; import { Step } from '~/ui/components/Step'; import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +The following guide explains how to install and configure `expo-dev-client` in an existing React Native project. -The installation steps on this page are only required to add the `expo-dev-client` library to a React Native or a bare project. To add the `expo-dev-client` library to an existing managed project, see ["Create a development build"](/develop/development-builds/create-a-build/). + -If you're starting your project, you can create a new project with our `with-dev-client` template. Run the following command to initialize the project: +If you're starting a project, you can create a new project with the `with-dev-client` template. Run this command to initialize the project: -Otherwise, if you already have an existing React Native or a bare project, follow the steps below to add `expo-dev-client` to it. + - + -## Install Expo modules +You may be reading the wrong guide then! To use `expo-dev-client` in a project that uses [CNG](/workflow/continuous-native-generation/), see ["Create a development build"](/develop/development-builds/create-a-build/). -If you created your project with `npx react-native init` and do not have any other Expo packages installed, **you will need to [install Expo modules](/bare/installing-expo-modules)** before proceeding. + -Otherwise, if you already have `expo` and/or other Expo modules up and running, you can skip this step. +## Prerequisites - +**The `expo` package must be installed and configured**: if you created your project with `npx react-native init` and do not have any other Expo packages installed, you will need to [install Expo modules](/bare/installing-expo-modules) before proceeding. - +## Installation + + ## Install expo-dev-client @@ -43,19 +47,27 @@ If your project doesn't have an **ios/** directory, you can skip this step. - + ## Configure deep links -Development builds use deep links to open projects from the QR code. If you have added a custom deep link scheme to your project, your development build will use it. However, if this isn't the case, you need to configure the deep link support for your app. The `uri-scheme` package will do this for you once you have chosen a scheme. +Expo CLI uses a deep link to launch your project, and it's also useful if you use plan to [use `expo-dev-client` for launching preview updates](/eas-update/getting-started/) if you have added a custom deep link scheme to your project. If you haven't configured a `scheme` for your app yet to support deep linking, then you can use `uri-scheme` package to do this for you. -']} /> +', + ]} +/> For more information, see [uri-scheme package](https://www.npmjs.com/package/uri-scheme). - + ## Add additional optional configuration @@ -71,10 +83,10 @@ For more information, see [Error handling](/develop/development-builds/use-devel - + -## Build and install +## Build and install the app -You're now ready to [build your first development build](/develop/development-builds/create-a-build/#initialize-eas-build). +Create a debug build of your app using the tools of your choice. For example, you can do this [locally with Expo CLI](/guides/local-app-development/) or [in the cloud with EAS Build](/develop/development-builds/create-a-build/). diff --git a/docs/pages/bare/installing-expo-modules.mdx b/docs/pages/bare/installing-expo-modules.mdx index e941aac57a303..c686f9ae659e2 100644 --- a/docs/pages/bare/installing-expo-modules.mdx +++ b/docs/pages/bare/installing-expo-modules.mdx @@ -12,7 +12,7 @@ To use Expo modules in your app, you will need to install and configure the `exp The `expo` package has a small footprint; it includes only a minimal set of packages that are needed in nearly every app and the module and autolinking infrastructure that other Expo SDK packages are built with. Once the `expo` package is installed and configured in your project, you can use `npx expo install` to add any other Expo module from the SDK. -Depending on how you [initialized the project](/bare/overview/), there are two ways you can install the Expo modules: [automatic](#automatic-installation) or [manual](#manual-installation). +Depending on how you [initialized the project](/bare/overview/), there are two ways you can install the Expo modules: [automatically](#automatic-installation) or [manually](#manual-installation). ## Automatic installation diff --git a/docs/pages/bare/installing-updates.mdx b/docs/pages/bare/installing-updates.mdx index 8c8651b795fd6..e7546a390af6e 100644 --- a/docs/pages/bare/installing-updates.mdx +++ b/docs/pages/bare/installing-updates.mdx @@ -1,18 +1,32 @@ --- -title: Add expo-updates to an existing project -description: Learn how to add expo-updates to an existing React Native project. +title: Install expo-updates in a bare React Native project +sidebar_title: Install expo-updates +description: Learn how to install and configure expo-updates in bare React Native projects. --- import { Terminal } from '~/ui/components/Snippet'; import { DiffBlock } from '~/ui/components/Snippet'; +import { Collapsible } from '~/ui/components/Collapsible'; -The `expo-updates` library fetches and manages updates received from a remote server. It supports [EAS Update](/eas-update/introduction), a hosted service that serves updates for projects using the `expo-updates` library. +The `expo-updates` library fetches and manages updates to app JavaScript and assets received from a remote server. It supports [EAS Update](/eas-update/introduction), a hosted service that serves updates and provides a variety of tools for managing them. It can also be configured to work with a [custom server](/eas-update/custom-updates-server/). This guide explains how set it up for use with EAS Update. -> If you are creating a new project, we recommend using `npx create-expo-app --template bare-minimum` (or `yarn create expo-app --template bare-minimum`) instead of `npx react-native init` because it will handle the following configuration for you automatically. It includes the `expo-updates` [config plugin](/config-plugins/introduction/), which will handle the following steps for you. + -## Installation +If you are creating a new project, we recommend using `npx create-expo-app --template bare-minimum` (or `yarn create expo-app --template bare-minimum`) because it will handle the following configuration for you automatically. It includes the `expo-updates` [config plugin](/config-plugins/introduction/), which will handle the installation steps for you. + + + + + +You may be reading the wrong guide then! To use `expo-updates` in a project that uses [CNG](/workflow/continuous-native-generation/), refer to the [EAS Update "Get started" guide](/eas-update/getting-started/). -The `expo-updates` library requires that your project already has [Expo modules configured](/bare/installing-expo-modules). Be sure to install it before continuing. + + +## Prerequisites + +**The `expo` package must be installed and configured**: if you created your project with `npx react-native init` and do not have any other Expo packages installed, you will need to [install Expo modules](/bare/installing-expo-modules) before proceeding. + +## Installation To get started, install `expo-updates`: @@ -24,7 +38,7 @@ Then, install pods: Once installation is complete, apply the changes from the following diffs to configure `expo-updates` in your project. -## Configuration in JavaScript and JSON +### Configuration in JavaScript and JSON Modify the `expo` section of **app.json**. (If you originally created your app using `npx react-native init`, you will need to add this section.) The changes below add the updates URL to the Expo configuration. @@ -79,7 +93,7 @@ If you want to set up a [custom server](/eas-update/custom-updates-server) inste } ``` -## Configuration for iOS +### Configuration for iOS Add the file **Podfile.properties.json** to the **ios** directory: @@ -137,7 +151,7 @@ Add the **Supporting** directory containing **Expo.plist** to your project in Xc ``` -## Configuration for Android +### Configuration for Android Modify **android/app/build.gradle** to check for the JS engine configuration (JSC or Hermes) in Expo files: diff --git a/docs/pages/bare/overview.mdx b/docs/pages/bare/overview.mdx index 50384429751fe..2a952ec38e3ba 100644 --- a/docs/pages/bare/overview.mdx +++ b/docs/pages/bare/overview.mdx @@ -1,50 +1,37 @@ --- -title: 'Bare React Native: Overview' +title: Overview of using Expo with existing React Native apps sidebar_title: Overview hideTOC: true -description: An overview of bare React Native apps with Expo tools. +description: Learn how to use Expo tools and services with existing React Native apps. --- import { BoxLink } from '~/ui/components/BoxLink'; import { Terminal } from '~/ui/components/Snippet'; import { DEMI, CODE } from '~/ui/components/Text'; +import { + BookOpen02Icon, + Rocket02Icon, + Lightbulb01Icon, + RefreshCw02Icon, + BuildArtifactIcon, + ChevronUpDoubleIcon, +} from '@expo/styleguide-icons'; -A bare React Native app is a project where developers make direct changes to their native **android** and **ios** project directories rather than continuously generating them on demand using [app config](/workflow/configuration/) and [prebuild](/workflow/prebuild). All tools and services offered by Expo including [EAS](/eas), Expo CLI, and the libraries in the Expo SDK, are built around bare React Native apps. +If you have a React Native app that doesn't use any Expo tools, you might be wondering what Expo can provide for you, why you might want to use Expo tools and services, and how to get started. -## Prerequisites +**All tools and services provided by Expo work great in any React Native app**. -Before you get started with a React Native app, make sure you have set up your developer environment from [React Native](https://reactnative.dev/docs/environment-setup). +You can use [EAS](/eas) to get quickly set up with a professional CI/CD workflow for building, reviewing, deploying, and updating your apps. [Expo CLI](/more/expo-cli/) provides the best command-line experience for working with React Native. The [Expo SDK](/versions/latest/) is an extended standard library for React Native. It gives developers high-quality, well maintained native libraries that use consistent API conventions to make them easier to learn and use. -## Get started +If you've ever written a native module for React Native, you'll be surprised how much easier it is to build and maintain modules with the idiomatic Swift and Kotlin DSL provided by the [Expo Modules API](/modules/overview/). -To bootstrap a new React Native project, use `create-expo-app` and run the following command: +There's so much more to explore, and the links below will help you to explore the options available to you. - - -> If you have an existing project or want to bootstrap with `npx react-native init`, then you need to [install the `expo` package](/bare/installing-expo-modules) manually. - -Navigate into your project directory, and run the following commands to build the app locally for each platform: - - - -> Learn more about [compiling native apps](/more/expo-cli/#compiling). - -## Next steps +## Next Steps If you have already initialized a React Native app without create-expo-app, learn @@ -54,22 +41,38 @@ Navigate into your project directory, and run the following commands to build th href="/bare/installing-expo-modules" /> + + + - - Automate your native directories using the app.json. - - } + Icon={RefreshCw02Icon} + description="Learn how to simplify maintaining your native projects by generating them on demand from configuration." href="/guides/adopting-prebuild" /> diff --git a/docs/pages/brownfield/installing-expo-modules.mdx b/docs/pages/brownfield/installing-expo-modules.mdx new file mode 100644 index 0000000000000..3d1f2bfc6ab54 --- /dev/null +++ b/docs/pages/brownfield/installing-expo-modules.mdx @@ -0,0 +1,193 @@ +--- +title: Install Expo modules +description: Learn how to prepare your existing native project to install and use Expo modules and the module API. +--- + +import InstallSection from '~/components/plugins/InstallSection'; +import { DiffBlock, Terminal } from '~/ui/components/Snippet'; +import { YesIcon, NoIcon } from '~/ui/components/DocIcons'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { Step } from '~/ui/components/Step'; + +> **warning** These instructions may not work for all projects. Support for integrating Expo modules into existing projects is still experimental. If you encounter issues, [create an issue on GitHub](https://github.com/expo/expo/issues). + +## Prerequisites + +You should have a native project with React Native installed and configured to render a root view. If you don't have this yet, you can follow [the "Integration with Existing Apps" guide](https://reactnative.dev/docs/integration-with-existing-apps) on the React Native docs and then return here. + +## Install the `expo` package + +First, add the `expo` package to your project. Ensure you are using a version of the `expo` package that is compatible with the React Native version in your project. [Learn more](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version). + + + +## Configure your Android app + + + Add the following to the `gradle.properties` file in the `android` directory: + + + + + Add the following to the `setting.gradle` file in the `android` directory: + + + + + From the `android` directory, run the following command: + + Once this completes, run the following command: + + + + + **(Optional)** Complete the following steps if you would like to use [lifecycle listeners](/modules/android-lifecycle-listeners/) + in your app. If you do not set up lifecycle listeners, then additional setup will be required for each module that uses them. + +If you already have a class that extends the `Application` class you can move to step 3. +If you do not have it, we need to create one. Add a file called `MainApplication.kt` file to your `android/app/src/main/java/com/` directory with the following content: + +/MainApplication.kt b/android/app/src/main/java/com//MainApplication.kt +new file mode 100644 +index 0000000..2c8525a +--- /dev/null ++++ b/android/app/src/main/java/com//MainApplication.kt +@@ -0,0 +1,19 @@ ++package ++ ++import android.app.Application ++import android.content.res.Configuration ++import com.facebook.soloader.SoLoader ++import expo.modules.ApplicationLifecycleDispatcher ++ ++class MainApplication() : Application() { ++ override fun onCreate() { ++ super.onCreate() ++ ApplicationLifecycleDispatcher.onApplicationCreate(this) ++ } ++ ++ override fun onConfigurationChanged(newConfig: Configuration) { ++ super.onConfigurationChanged(newConfig) ++ ApplicationLifecycleDispatcher.onConfigurationChanged(this, newConfig) ++ } ++}`} /> + + +Register the class in the `AndroidManifest.xml` file. + + + + +If you have your own class extending `Application`, you can add the following to it: + +/MainApplication.kt b/android/app/src/main/java/com//MainApplication.kt +new file mode 100644 +index 0000000..2c8525a +--- /dev/null ++++ b/android/app/src/main/java/com//MainApplication.kt +@@ -0,0 +1,19 @@ +class MainApplication() : Application() { + override fun onCreate() { + super.onCreate() ++ ApplicationLifecycleDispatcher.onApplicationCreate(this) + } ++ ++ override fun onConfigurationChanged(newConfig: Configuration) { ++ super.onConfigurationChanged(newConfig) ++ ApplicationLifecycleDispatcher.onConfigurationChanged(this, newConfig) ++ } + +}`} /> +Override `onConfigurationChanged` if you have not done so already. + + + + +## Configure your iOS app + + + Add the following to your `Podfile` in the `ios` directory: + ' do ++ use_expo_modules! + config = use_native_modules! + `} + /> + + + + Open your `ios` directory in Xcode. From the project navigator, select your project and then + select your app target under `TARGETS`. In `Build Settings`, using the search bar, search for + `ENABLE_USER_SCRIPT_SANDBOXING`. If it is not already, set its value to `No`. + + + + Run `pod install` in the `ios` directory. + + You will need to do this everytime you add a dependency that uses native code. + + + + **(Optional)** Complete the following if you would like to use [AppDelegate subscribers](/modules/appdelegate-subscribers/). If you do not set up AppDelegate subscribers, then additional setup will be required for each module that uses them. + /AppDelegate.swift b/ios//AppDelegate.swift +index ff83531..bd8651d 100644 +--- a/ios//AppDelegate.swift ++++ b/ios//AppDelegate.swift +@@ -1,31 +1,29 @@ + import UIKit ++import ExpoModulesCore + + @main +-class AppDelegate: UIResponder, UIApplicationDelegate { ++class AppDelegate: ExpoAppDelegate { + +- func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { ++ override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { +- return true ++ super.application(application, didFinishLaunchingWithOptions: launchOptions) + } + `} + /> + diff --git a/docs/pages/brownfield/overview.mdx b/docs/pages/brownfield/overview.mdx new file mode 100644 index 0000000000000..1440c4586cbbc --- /dev/null +++ b/docs/pages/brownfield/overview.mdx @@ -0,0 +1,47 @@ +--- +title: Integrating Expo tools into existing native apps +sidebar_title: Overview +hideTOC: true +description: An overview of how you can integrate Expo tools into existing native apps ("brownfield" apps). +--- + +import { BoxLink } from '~/ui/components/BoxLink'; +import { Terminal } from '~/ui/components/Snippet'; +import { DEMI, CODE } from '~/ui/components/Text'; + +An existing native app that was built using another technology, whose main entry point is *not* a React Native view, is commonly referred to as a "brownfield" app. For example, if your app was built using UIKit and Swift, and you want to use React Native for a single screen then that is considered an "existing native app" and "brownfield". + +In contrast, "greenfield" apps are those which are created using Expo or React Native from the start or where React Native is the entry point and where all other UI branches off from. + +By these definitions, if you have an "existing native app" for Android or iOS and you want to learn how to use Expo and React Native in your project (perhaps on a single screen or even a single feature), then this guide is for you. + +## Compatibility with existing native apps + +> **info** Support for integrating Expo modules into existing native projects is still experimental. If you encounter issues, [create an issue on GitHub](https://github.com/expo/expo/issues). Not all features of the above tools/services will when used in the context of an existing native app. + +Expo is primarily built with greenfield apps in mind — not all Expo tools and services are compatible with existing native projects. + +| Tool/Service | Supports brownfield? | +| ---------------------------------------------------------------------------------------------------- | -------------------- | +| [Expo SDK](/versions/latest/) - an extended standard library for React Native | Yes | +| [Expo Modules API](/modules/overview/) - build native extensions using an idiomatic Swift/Kotlin API | Yes | +| [Expo Router](/router/introduction/) - file-based routing and navigation | No | +| [Expo CLI](/more/expo-cli/) - tools to run and develop your app from your terminal | No | +| [Expo Dev Client](/versions/latest/sdk/dev-client/) - adds in-app developer tooling to Debug builds | No | +| [EAS Build](/build/introduction/) - a CI/CD service built specifically for Expo/React Native | Yes | +| [EAS Submit](/submit/introduction/) - a hosted service that uploads your app to stores | Yes | +| [EAS Update](/eas-update/introduction/) - instant updates of your app JavaScript and assets | No | + +## Next steps + + + + diff --git a/docs/pages/develop/development-builds/create-a-build.mdx b/docs/pages/develop/development-builds/create-a-build.mdx index ccfbb128776da..e17fe75dbbc47 100644 --- a/docs/pages/develop/development-builds/create-a-build.mdx +++ b/docs/pages/develop/development-builds/create-a-build.mdx @@ -34,7 +34,7 @@ The following instructions cover both Android and iOS and physical devices and e -Apps that don't use [Continuous Native Generation](/workflow/continuous-native-generation/) will need to follow the ["Install development builds in bare React Native" guide](/bare/install-dev-builds-in-bare/). +Apps that don't use [Continuous Native Generation](/workflow/continuous-native-generation/) will need to follow the ["Install expo-dev-client in bare React Native" guide](/bare/install-dev-builds-in-bare/).