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 651c53f134791..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,19 +427,6 @@ const general = [ makePage('accounts/working-together.mdx'), makePage('accounts/sso.mdx'), ]), - 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/using-expo-client.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'), - ]), ], { 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..ae47c540888a2 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 exisitng 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 with `with-dev-client` template. Run the following 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..a4c95d4dcabe8 100644 --- a/docs/pages/bare/installing-updates.mdx +++ b/docs/pages/bare/installing-updates.mdx @@ -1,18 +1,31 @@ --- -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 +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 following 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 +37,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 +92,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 +150,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..5045c8ba45fba 100644 --- a/docs/pages/bare/overview.mdx +++ b/docs/pages/bare/overview.mdx @@ -1,50 +1,33 @@ --- -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. +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 ([with CNG](/workflow/continuous-native-generation/)) them using [app config](/workflow/configuration/) and [prebuild](/workflow/prebuild). -## Prerequisites +All tools and services provided by Expo, including [EAS](/eas), [Expo CLI](/more/expo-cli/), and [Expo SDK libraries](/versions/latest/), work great whether you use CNG to generate your native directories or you modify them directly (bare workflow). -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). +{/* TODO: add information here about why you would want to use Expo tools and services in existing React Native apps */} -## Get started - -To bootstrap a new React Native project, use `create-expo-app` and run the following command: - - - -> 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 +37,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 index 92ca9e62c9205..914fc07d9eaac 100644 --- a/docs/pages/brownfield/installing-expo-modules.mdx +++ b/docs/pages/brownfield/installing-expo-modules.mdx @@ -9,17 +9,19 @@ 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 not, you can follow [this](https://reactnative.dev/docs/integration-with-existing-apps) guide to get set up. +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 Expo modules +## 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). -### iOS +## Configure your iOS app Add the following to your `Podfile` in the `ios` directory: @@ -57,7 +59,7 @@ index 2d3a979..825a9d4 100644 - (Optional) Complete the following if you would like to use Expo modules lifecycle listeners. + **(Optional)** Complete the following if you would like to use [AppDelegate subscribers](/modules/appdelegate-subscribers/). /AppDelegate.swift b/ios//AppDelegate.swift index ff83531..bd8651d 100644 @@ -80,7 +82,7 @@ index ff83531..bd8651d 100644 /> -### Android +## Configure your Android app Add the following to the `gradle.properties` file in the `android` directory: @@ -120,7 +122,7 @@ index a26c7c6..dd8802a 100644 - (Optional) Complete the following steps if you would like to use Expo modules lifecycle listeners + **(Optional)** Complete the following steps if you would like to use [lifecycle listener](/modules/android-lifecycle-listeners/) in your app: If you already have a class that extends the `Application` class you can move to step 3. @@ -188,8 +190,4 @@ class MainApplication() : Application() { Override `onConfigurationChanged` if you have not done so already. - - -## Limitations - -Here we list limitations. + \ No newline at end of file diff --git a/docs/pages/brownfield/overview.mdx b/docs/pages/brownfield/overview.mdx index 8693bd324b4ec..2437f5e0a72c4 100644 --- a/docs/pages/brownfield/overview.mdx +++ b/docs/pages/brownfield/overview.mdx @@ -9,33 +9,39 @@ import { BoxLink } from '~/ui/components/BoxLink'; import { Terminal } from '~/ui/components/Snippet'; import { DEMI, CODE } from '~/ui/components/Text'; -If you already have a native app for Android and/or iOS and want to learn how to use Expo and React Native in your project, perhaps on a single screen or feature to start, this guide is for you. This type of app is commonly referred to as a "brownfield" app in the React Native ecosystem (as opposed to "greenfield" apps, which are created from scratch using Expo and React Native). +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" / "brownfield". -## Compatibility +In contrast, "greenfield" apps are those which are created from using Expo / 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 and/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/) | Yes | -| [Expo Modules API](/modules/overview/) | Yes | -| [Expo Router](/router/introduction/) | No | -| [Expo CLI](/more/expo-cli/) | No | -| [Expo Dev Client](/versions/latest/sdk/dev-client/) | No | -| [EAS Build](/build/introduction/) | Yes | -| [EAS Submit](/submit/introduction/) | Yes | -| [EAS Update](/eas-update/introduction/) | No | +| 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/).