diff --git a/docs/.vale/writing-styles/expo-docs/HeadingCase.yml b/docs/.vale/writing-styles/expo-docs/HeadingCase.yml index f7e9a7cc71760..5ccf85d382e01 100644 --- a/docs/.vale/writing-styles/expo-docs/HeadingCase.yml +++ b/docs/.vale/writing-styles/expo-docs/HeadingCase.yml @@ -151,6 +151,7 @@ exceptions: - '.*New Architecture.*' - '.*Node.*' - '.*npm.*' + - '.*OTA.*' - '.*OTF.*' - '.*Organizations.*' - '.*Package.*' diff --git a/docs/common/error-utilities.ts b/docs/common/error-utilities.ts index d6b6c53830b16..4b7d06bf04e55 100644 --- a/docs/common/error-utilities.ts +++ b/docs/common/error-utilities.ts @@ -404,7 +404,7 @@ const RENAMED_PAGES: Record = { '/versions/latest/sdk/payments/': '/versions/latest/sdk/stripe/', '/distribution/app-icons/': '/develop/user-interface/app-icons/', '/guides/using-libraries/': '/workflow/using-libraries/', - '/tutorial/': '/tutorial/introduction/', + '/tutorial/': '/tutorial/overview/', // EAS Update '/eas-update/developing-with-eas-update/': '/eas-update/develop-faster/', diff --git a/docs/constants/navigation.js b/docs/constants/navigation.js index 3e5bb4c5dba2c..118a159dd9d21 100644 --- a/docs/constants/navigation.js +++ b/docs/constants/navigation.js @@ -450,6 +450,7 @@ const general = [ ]; const learn = [ + makeSection('', [makePage('tutorial/overview.mdx')]), makeSection( 'Get started', [ @@ -466,6 +467,25 @@ const learn = [ ], { expanded: true } ), + makeSection( + 'EAS tutorial', + [ + makePage('tutorial/eas/introduction.mdx'), + makePage('tutorial/eas/configure-development-build.mdx'), + makePage('tutorial/eas/android-development-build.mdx'), + makePage('tutorial/eas/ios-development-build-for-simulators.mdx'), + makePage('tutorial/eas/ios-development-build-for-devices.mdx'), + makePage('tutorial/eas/multiple-app-variants.mdx'), + makePage('tutorial/eas/internal-distribution-builds.mdx'), + makePage('tutorial/eas/manage-app-versions.mdx'), + makePage('tutorial/eas/android-production-build.mdx'), + makePage('tutorial/eas/ios-production-build.mdx'), + makePage('tutorial/eas/team-development.mdx'), + makePage('tutorial/eas/using-github.mdx'), + makePage('tutorial/eas/next-steps.mdx'), + ], + { expanded: true } + ), makeSection( 'UI programming', [ diff --git a/docs/pages/_app.tsx b/docs/pages/_app.tsx index 7f6124251c015..cfd5b7e4d5f9b 100644 --- a/docs/pages/_app.tsx +++ b/docs/pages/_app.tsx @@ -10,6 +10,7 @@ import { useNProgress } from '~/common/use-nprogress'; import DocumentationElements from '~/components/page-higher-order/DocumentationElements'; import { AnalyticsProvider } from '~/providers/Analytics'; import { CodeBlockSettingsProvider } from '~/providers/CodeBlockSettingsProvider'; +import { TutorialChapterCompletionProvider } from '~/providers/TutorialChapterCompletionProvider'; import { markdownComponents } from '~/ui/components/Markdown'; import * as Tooltip from '~/ui/components/Tooltip'; @@ -58,23 +59,25 @@ export default function App({ Component, pageProps }: AppProps) { return ( - - - - - - - - + + + + + + + + + + ); diff --git a/docs/pages/tutorial/eas/android-development-build.mdx b/docs/pages/tutorial/eas/android-development-build.mdx new file mode 100644 index 0000000000000..9085a095795e7 --- /dev/null +++ b/docs/pages/tutorial/eas/android-development-build.mdx @@ -0,0 +1,173 @@ +--- +title: Create and run a cloud build for Android +sidebar_title: Android development build +description: Learn how to configure a development build for Android devices and emulators using EAS Build. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; + +In this chapter, we'll create a development build that can run on Android with EAS Build. + +The process for creating and running a build on Android devices or emulators is identical, with differences only in the installation of the development build. + +## Create a build for the development profile + +For Android, the development build must be in the **.apk**. While the default Android format is **.aab**, which is ideal for Google Play Store distribution, it cannot be installed on devices or emulators. + +To create a **.apk**: + +- In **eas.json**, make sure that `developmentClient` is set to `true` under `build.development` profile. +- Then, run the `eas build` command with `android` as the platform and `development` as the build profile: + + + + > **info** **Tip**: Next time you run `eas build` command, you can also use `-p` to specify the platform. It is short for `--platform`. + +This command prompts us with the following questions: + +- **What would you like your Android application id to be?** Press return to select the default value provided for this prompt. This will add [`android.package`](/versions/latest/config/app/#package) in **app.json**. +- **Generate a new Android Keystore**? Press Y. + +After responding, the build will queue up, and we can track its progress via a provided link by the EAS CLI in the Expo dashboard: + + + + + +The build details page displays the build type, profile, Expo SDK version, app version, version code, last commit hash, and the identity of the developer or account owner who initiated the build. + +In the above image, the current status of the **Build artifact** shows that the build is in progress. Upon completion, this section will offer an option to download the build. The **Logs** outlines every step taken during the Android build process on EAS Build. For the sake of brevity, we won't explore each step in detail here. To learn more, see [Android build process](/build-reference/android-builds/). + + + + + +Also known as the package name of our Android app, it stores the value in DNS reverse notation format (`com.owner.appname`). Each component of this notation should start with a lowercase letter. + +For example, our example app has `com.owner.stickersmash` where `com.owner` is the domain and `stickermsash` is our app name. + + + +## Android device + + + +### Install development build + +Once the build finishes, the **Build artifact** section gets updated, indicating that the build is complete: + + + +This section provides the methods available for running the development build on an Android device: Expo Orbit and Install button. + +[Expo Orbit](https://expo.dev/orbit) allows for seamless installation of the development build on an Android device. To use this method: + +- Connect our Android device to our local machine using USB. +- Open the Orbit menu bar app. +- Select the **Device** in the Orbit app. + + + +- On the Expo dashboard, under **Build artifact**, click the **Open with Orbit**. + +After the build is installed, the Orbit app launches the development build on the device. + + + +The **Install** button in the **Build artifact** generates a QR code for installation: + +- Click **Install** to display a popup with the QR code. + + + +- Scan the QR code with our Android device's camera to open the build link in the default web browser. +- Tap the **Install** button on the webpage to download the **.apk** file. +- Once downloaded, open the **.apk** to start the installation process. +- If an **Unsafe app blocked message** appears, select **Install anyway**. This warning can safely be ignored as the source of the **.apk** (which we generated) is trusted. + + + + + + + + + +### Run development build + +Start the development server by running `npx expo start` from the project directory. Once the server is running, press a in the terminal window to open the project: + + + + + +## Android Emulator + + + +### Install the development build + +In the terminal, once the build finishes, EAS CLI prompts us by asking whether we want to run the build on an Android Emulator. Press Y. + + + + + +Alternatively, Expo Orbit can be used for installation. From **Build artifact** on the Expo dashboard, click **Open with Expo Orbit** to install the development build on the Android Emulator. + + + + + + + +### Run the development build + +Start the development server by running `npx expo start` from the project directory. Once the server is running, press a in the terminal window to open the project: + + + + + +## Summary + + + We successfully used EAS Build to create and run development builds on Android devices and + emulators, and learned about .apk and .aab file formats. + + } + nextChapterDescription="In the next chapter, Learn how to configure a development build for iOS Simulators using EAS Build and get it running." + nextChapterTitle="Create and run a cloud build for iOS Simulator" + nextChapterLink="/tutorial/eas/ios-development-build-for-simulators/" +/> diff --git a/docs/pages/tutorial/eas/android-production-build.mdx b/docs/pages/tutorial/eas/android-production-build.mdx new file mode 100644 index 0000000000000..e3aecb67a264b --- /dev/null +++ b/docs/pages/tutorial/eas/android-production-build.mdx @@ -0,0 +1,309 @@ +--- +title: Create a production build for Android +sidebar_title: Android production build +description: Learn about the process of creating a production build for Android and automating the release process. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; +import { CODE } from '~/ui/components/Text'; + +In this chapter, we'll create our example app's production version and submit it to the Google Play Store. We'll also explore how to automate the creation and release of new app versions. + +## Prerequisites + +To publish and distribute an app on the Google Play Store, we need: + +- **Google Play Developer Account:** Must have a paid developer account. For details on setting one up, visit the [Google Play sign-up page](https://play.google.com/apps/publish/signup/). +- **Google Service Account:** We'll need a Google Service Account email and JSON key to automate the app submission process. Follow the detailed instructions in our guide on [creating a Google Service Account](https://github.com/expo/fyi/blob/main/creating-google-service-account.md), then return to this guide. This is optional but required for automating the release process. +- **Production build profile:** Ensure that a `production` build profile is present in your **eas.json**, which is added by default. + +## Production build for Android + +A [production Android build](/build/eas-json/#production-builds) has a **.aab** format which is optimized for distribution on the Google Play Store. Unlike **.apk** builds, **.aab** files can only be distributed and installed through the Google Play Store. + + + +## Create a production build + +To create an Android production build using the default `production` profile, open your terminal and execute the following command. Since `production` is set as the default profile in the EAS configuration, there is no need to specify it explicitly with the `--profile` flag. + + + +The above command will queue the build. Notice in the Expo dashboard that the **Version Code** is auto-incremented. + + + + + +## Create an app on the Google Play Console + +To upload the app to the Google Play Store for the first time, we need to: + +- Go to the Google Play dashboard. +- On the **Home** page, click **Create app** to make a new app. + + + +- Fill out our app details and click the **Create app** button. + + + + + + + +## Release an internal testing version + +After the app is created on Google Play Console, it redirects us to the app's Dashboard screen. We need to prepare an internal test version of our app. + +- Click **Start testing now** on the **Dashboard**. + + + +- Create an email list of users under **Internal Testing** > **Testers for the internal testing release**. + + + +- Google Play Console prompts us to create a **Release**. +- To create a new release, go to **Releases** and click **Create new release**. + + + +- To store the signing key, go to **App integrity** > **App bundles** and click **Choose signing key** > **Use Google-generated key**. + + + + + + + +## Upload the app binary + +After EAS has created a production build: + +- Open the EAS dashboard and click on **Download** to get the **.aab** file. + + + +- Return to the Google Play Console and go to **App bundles**. Click on **Upload** to add the **.aab**. +- Provide the release details for our app and click on **Next**. +- On the following screen, click on **Save and publish**. + + + + + + + +## Share the internal release version + +Under **Track Summary**, we see that the latest release shows a temporary app name. This is because our app is not reviewed yet. + + + +Under **Releases**, we see that the app is available to internal testers. To share the app with a team of testers: + +- Open the Internal testing dashboard, then click on **View release details**. +- Click on **copy link** under **How testers join your test**. + + + +- On the device, open the test email and follow the steps to download the app. + + + +- The testing email holder needs to accept the invite, and once accepted, the app can be installed on the device. + + + + + +> **info** **Tip**: To publish an app on the Play Store, in the Google Dashboard, finish the steps under **Set up your app**. These steps are required before releasing the app on the Play Store for the first time. You'll have to provide details like a link to a privacy policy, a target audience, data safety and so on. + +> **Complete app store listing**: To prepare the app for store listing, see [Create app store assets](/guides/store-assets/) on how to create screenshots and previews. + + + +To promote our internal test release version to **alpha**, in Google Play Store Console: + +- Go to internal testing and click **Promote release**. +- Open the dropdown menu and click **Closes testing** > **Closed testing - Alpha**. + + + + + + + +## Add Google Service Account permissions key + +From now on, we can use [EAS Submit](/submit/introduction/) to automate releases and avoid the manual process. To do that, we need to add the service account key to our project's **eas.json**. + +After following the Google Service Account guide steps, we can use the downloaded JSON key: + +- Open our project and copy the JSON file from the Google Service Account to the project's root directory. +- To secure sensitive data, ensure this file is excluded from version control by listing it in our **.gitignore**. + + + + + +## Internal release + +Let's add the path to the Google Service Account file path in **eas.json**. + +- Under `submit.production` profile, add `android.serviceAccountKeyPath` and the relative file path as its value: + +{/* prettier-ignore */} +```json +{ + /* @hide ... */ /* @end */ + "submit": { + "production": { + /* @info Add the path to the Google Service Account file and set track to internal */ + "android": { + "serviceAccountKeyPath": "./service-account-file.json", + "track": "internal" + } + /* @end */ + } + } +} +``` + +In the above snippet, we're also adding [`track`](/eas/json/#track) property and setting its value to `internal`. This will enable the `eas submit` command to upload our production build and release it for internal testing on the Google Play Store. + +- Now run the `eas submit` command to release a new internal testing version: + + + +- This command will automatically create a new internal release version in Google Play Console: + + + + + + + +## Production release + +To release the app for production: + +- Change the value for `track` to `production` in **eas.json**: + +```json +{ + /* @hide ... */ /* @end */ + "submit": { + "production": { + "android": { + "serviceAccountKeyPath": "./service-account-file.json", + /* @info Change the track to production */ + "track": "production" + /* @end */ + } + } + } +} +``` + +- We can also use the same EAS Build we did for the internal testing release. Run the `eas submit` command to release to the Play Store: + + + +- To create a track and submit our app to the Google Play Store's review process, we need to **Release** > **Production** and under **Releases**, select the build we want to send for review. + + + + + + + +## Automated release + +For subsequent releases in future, we can streamline the process by combining build creation and Play Store submission into a single step by using the [`--auto-submit`](/build/automate-submissions/) flag with `eas build`: + + + + + +## Summary + + + We successfully created a production-ready Android build, discussed manual and automated + uploading to Google Play Store using eas submit, and automated the release + process with the --auto-submit. + + } + nextChapterDescription=" +In the next chapter, learn about the process of creating a production build for iOS." + nextChapterTitle="Create a production build for iOS" + nextChapterLink="/tutorial/eas/ios-production-build/" +/> diff --git a/docs/pages/tutorial/eas/configure-development-build.mdx b/docs/pages/tutorial/eas/configure-development-build.mdx new file mode 100644 index 0000000000000..a84098e0f7f3c --- /dev/null +++ b/docs/pages/tutorial/eas/configure-development-build.mdx @@ -0,0 +1,199 @@ +--- +title: Configure a development build in cloud +sidebar_title: Configure development build +description: Learn how to configure a development build for a project using EAS Build. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { CODE } from '~/ui/components/Text'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; + +In this chapter, we'll set up and configure a development build with EAS for our example app. + +## Understanding development builds + +Let's start by learning about what are development builds and why we need them. + +A [development build](/develop/development-builds/introduction/) is a debug version of our project. It is optimized for quick iterations when creating an app. It contains the [`expo-dev-client`](/versions/latest/sdk/dev-client/) library, which offers a robust and complete development environment. This setup allows us to integrate any native library or change code inside the [native directories](/workflow/overview/#android-and-ios-native-projects) as required. + +### Key highlights + +> **Note:** If you are familiar with [Expo Go](/get-started/expo-go/), think of a development build as a customizable version of Expo Go that is unique to the requirements of a project. + +| Feature | Development Builds | Expo Go | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| **Development phase** | Offers web-like iteration speed for mobile app development. | Allows for quick iteration and testing of Expo SDK projects using the client app. | +| **Collaboration** | Facilitates team testing with shared native runtime. | Easy project sharing via QR codes on a device. | +| **Third-party libraries support** | Full support for any [third-party library](/workflow/using-libraries/#third-party-libraries), including those that require custom native code. | Limited to libraries within the Expo SDK, not suitable for custom native dependencies. | +| **Customization** | Extensive customization with [config plugins](/config-plugins/introduction/) and direct access to native code. | Limited customization with a focus on Expo SDK capabilities without direct native code modification. | +| **Intended use** | Ideal for full-fledged app development aimed at store deployment, offering a complete development environment and tools. | Ideal for learning, prototyping, and experimenting. Not recommended for production apps. | + + + +## Install expo-dev-client library + +To initialize our project for a development build, let's [`cd`](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line#basic_built-in_terminal_commands) inside our project directory and run the following command to install the library: + + + +### Start the development server + +Run the `npx expo start` to start the [development server](/get-started/start-developing/#start-a-development-server): + + + +This command starts the metro bundler. In the terminal window, we see the QR code followed by the `Metro waiting on...` and a manifest URL: + + + +Let's notice the changes installing the `expo-dev-client` library: + +- The manifest URL contains `expo-development-client` along with the app scheme +- The development server now operates for a development build (instead of Expo Go). + +Since we do not have a development build installed on one of our devices or an emulator/simulator, we can't run our project yet. + + + + + +## Initialize a development build + +### Install EAS CLI + +We need to install the EAS Command Line Interface (CLI) tool as a global dependency on our local machine. Run the following command: + + + +### Log in or sign up for an Expo account + +> If you have an Expo account and are signed in using Expo CLI, skip this step. If you don't have an Expo account, [sign up here](https://expo.dev/signup) and proceed with the login command described below. + +To log in, run the following command: + + + +This command asks for our Expo account email or username and password to complete the login. + +### Initialize and link the project to EAS + +For any new project, the first step is to initialize and link it to the EAS servers. Run the following command: + + + +On running, this command: + +- Requests verification of the account owner by entering our Expo account credentials and asks if we want to create a new EAS project: + + ```sh + # Output after running eas init + ✔ Which account should own this project? > your-username + ✔ Would you like to create a project for @your-username/sticker-smash? … yes + ✔ Created @your-username/sticker-smash + ✔ Project successfully linked (ID: XXXX-XX-XX-XXXX) (modified app.json) + ``` + +- Creates EAS project and provides a link to that project which we can open in the Expo dashboard: + + + +- Generates a unique `projectId` and links this EAS project to the example app on our development machine. +- Modifies **app.json** to include [`extra.eas.projectId`](/versions/latest/sdk/constants/#easconfig) and updates its value with the unique ID created. + +What is projectId in app.json?}> + +When `eas init` runs, it associates a unique identifier for our project in **app.json** under `extra.eas.projectId`. The value of this property is used to identify our project on EAS servers. + +```json +{ + "extra": { + "eas": { + "projectId": "0cd3da2d-xxx-xxx-xxx-xxxxxxxxxx" + } + } +} +``` + + + + + + + +## Configure project for EAS Build + +To set up our project for EAS Build, run the following command: + + + +On running, this command: + +- Prompts to select a platform: **Android**, **iOS**, or **All**. Since we are creating Android and iOS apps, let's select **All**. +- Creates **eas.json** in the root of our project's directory with the following configuration: + +```json eas.json +{ + "cli": { + "version": ">= 8.0.0" + }, + + "build": { + "development": { + "developmentClient": true, + "distribution": "internal" + }, + + "preview": { + "distribution": "internal" + }, + + "production": {} + }, + + "submit": { + "production": {} + } +} +``` + +This is the default configuration for **eas.json** in a new project. It does two things: + +- Defines the current EAS CLI version. +- Adds three [build profiles](/build/eas-json/#build-profiles): `development`, `preview`, and `production`. + + + + + +**eas.json** is a collection of different build profiles. Each profile is tailored with distinct configurations to produce specific build types. These profiles can also include platform-specific settings for Android or iOS. + +Currently, our focus is on the `development` profile, which includes the following configuration: + +- [`developmentClient`](/eas/json/#developmentclient): Enabled (`true`) for creating a debug build. It loads the app using the `expo-dev-client` library, which provides development tools and generates a build artifact for device or emulator/simulator installation and allows using the app for local development as it supports updating the JavaScript on the fly. +- [`distribution`](/eas/json/#distribution): Configured as `internal` to indicate that we want to share the build internally (instead of uploading it on app stores). + +> **Note**: Builds offer extensive customization options, including platform-specific settings and the ability to extend configurations across different build profiles. Learn more about [customizing build profiles](/build/eas-json/#build-profiles). + + + +## Summary + + diff --git a/docs/pages/tutorial/eas/index.js b/docs/pages/tutorial/eas/index.js new file mode 100644 index 0000000000000..f371260222346 --- /dev/null +++ b/docs/pages/tutorial/eas/index.js @@ -0,0 +1,3 @@ +import redirect from '~/common/redirect'; + +export default redirect('/tutorial/eas/introduction/'); diff --git a/docs/pages/tutorial/eas/internal-distribution-builds.mdx b/docs/pages/tutorial/eas/internal-distribution-builds.mdx new file mode 100644 index 0000000000000..60b6292d41a76 --- /dev/null +++ b/docs/pages/tutorial/eas/internal-distribution-builds.mdx @@ -0,0 +1,189 @@ +--- +title: Create and share internal distribution build +sidebar_title: Internal distribution build +description: Learn about what are internal distribution builds, why we need them, and how to create them. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { Tabs, Tab } from '~/ui/components/Tabs'; +import { CODE } from '~/ui/components/Text'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; + +In this chapter, we'll learn how to set up [internal distribution builds](/guides/sharing-preview-releases/#internal-distribution). + +## Internal distribution build + +Internal distribution builds are ideal for sharing updates with team members, allowing both technical and non-technical stakeholders to provide feedback directly. Unlike development builds, these do not require running a development server, simplifying the testing process. + +### Ways to distribute an app internally + +Both Google and Apple provide built-in mechanisms for sharing apps internally: + +- **Android**: Using Google Play beta +- **iOS**: Using TestFlight + +However, both of these traditional methods have their limitations. For example, TestFlight limits to one active build at a time. + +### EAS Build for faster distribution + +EAS Build speeds up the process. It creates shareable links for our builds and provides instructions on using them. It has a default configuration designed to facilitate internal distribution, offering a more efficient alternative to traditional methods. + +## Create an internal distribution build + +To create and distribute a build with EAS Build, we need to follow these steps: + + + +### Configure preview build profile + +From our initial setup in **eas.json**, we already have a default configuration that includes a `preview` build profile designed for internal distribution: + +```json eas.json +{ + "build": { + "preview": { + /* @info The distribution in preview profile has its value set to internal. */ + "distribution": "internal" + /* @end */ + } + } +} +``` + +This is all we need to create our first internal distribution build. The `preview` build profile from the above snippet has a `distribution` property whose value is set to `internal`. This value allows us to share our build URLs with anyone so they to install it on their device and do not require a development server to run the app. + +As discussed in the previous chapters, for non-app store builds, Android requires **.apk** and iOS needs **.ipa** formats. This applies to internal distribution builds as well. The `distribution` when set to `internal`, automatically creates the app binary in these file formats for devices. + + + + + +### Create + + + + + +- Use the `preview` profile to initiate an Android build: + + + +- This command triggers the EAS Build, and on the Expo dashboard, we can see the build's progress: + + + + + +Android app signing is non-restrictive. A new Android Keystore was generated for development builds, but since Android allows installing any compatible **.apk**, there's no need for a new keystore for preview builds. + + + + + + + +Apple has stricter rules for app distribution on iOS devices. We need an ad hoc provisioning profile, which allows explicitly listing the devices allowed to run the app. + +- To add more devices, use `eas device:create`. This command registers an iOS device and gives us a URL or QR code to share for device registration: + + + +- This command registers an iOS device for app installation, generating a shareable URL (or QR code) for device registration. + + > **info** **Tip**: This command enables device registration at any time. However, only builds created post-registration will work on the newly added device. + +- To create the preview build, we need to use the `preview` profile with the `eas build` command: + + + +- This command triggers the EAS Build, and on the Expo dashboard, we can see the build's progress: + + + +Alternative method to register devices using eas build:resign}> + +[`eas build:resign`](/app-signing/app-credentials/#re-signing-new-credentials) command can be used to re-sign an existing iOS **.ipa** with a new ad hoc provisioning profile, eliminating the need for a full rebuild. + + + + + + + + + + + +### Install + +Once the build finishes, the Build artifact section gets updated, indicating that the build is complete. This section provides the methods available for running the development build on an iOS device: Expo Orbit and Install button. + +- Open the build's detail page. If you are sharing the build with someone else, you can send them the link to the build. They'll be able to open the build's detail page or build artifact details which include Expo Orbit. +- Connect the Android or iOS device to our machine using USB. +- Open the Orbit menu bar app. +- Select the **Device** in the Orbit app. +- Under **Build artifact**, click the **Open with Orbit**. + + + +- Open the build's detail page. If you are sharing the build with someone else, you can send them the link to the build page. They'll be able to open it and see build artifact details which includes Expo Orbit. +- Click **Install** under the Build artifact section to display the **Install on a test device** popup. +- Copy the link from **Send a link to a device** section and send it to the test device. + + + + + + + + + +### Run + +Tap the app icon on your device to start the preview build. There is no need for a development server. + +Since we have already set up multiple app variants, we can see both the development and preview variants installed separately on our devices. For example: + +- On Android: + + + +- On iOS: + + + + + +## Summary + + diff --git a/docs/pages/tutorial/eas/introduction.mdx b/docs/pages/tutorial/eas/introduction.mdx new file mode 100644 index 0000000000000..a95d0475428b1 --- /dev/null +++ b/docs/pages/tutorial/eas/introduction.mdx @@ -0,0 +1,53 @@ +--- +title: 'EAS Tutorial: Introduction' +sidebar_title: Introduction +description: An introduction to the tutorial for building apps for Android and iOS using Expo Application Services (EAS) that covers the Build, Update, and Submit workflows. +--- + +import Highlight from '~/components/plugins/Highlight'; +import { BoxLink } from '~/ui/components/BoxLink'; +import { BookOpen02Icon } from '@expo/styleguide-icons'; + +## About this tutorial + +This tutorial will give you proficiency with [Expo Application Services (EAS)](https://expo.dev/eas) core services: [Build](/build/introduction/), [Submit](/submit/introduction/), and [Update](/eas-update/introduction/). When you complete the tutorial, you will know how to set up a professional mobile Continuous Integration (CI)/Continuous Development (CD) pipeline for your individual and team projects. + +This tutorial covers the following topics: + +- Use EAS Build to create and install a development build, then run it on a device, emulator, or simulator. +- Experience the benefits of using a development build instead of Expo Go. +- Implement workflows for sharing development builds with a team or external stakeholders. +- Automatically increment app build versions. +- Simultaneously install different app variants, like development and preview, on one device. +- Utilize EAS Update to create and deploy updates swiftly during the development phase. +- Automate build processes by integrating with a GitHub repository. + +These topics will give us the foundation needed to use EAS effectively and to approach more advanced topics when needed. + +## Prerequisites + +This tutorial is hands-on and designed to be completed in about two hours. You will need an existing Expo project to follow along and set it up locally on your machine. Options include: + +- Continuing with the Sticker Smash app from our previous tutorial. If new, download it from [GitHub](https://github.com/amandeepmittal/sticker-smash-expo-tutorial-app). +- Starting a new project with [`npx create-expo-app`](/get-started/create-a-project/). +- Using a bare React Native project. Ensure the `expo` package is installed, which you can do [automatically](/bare/installing-expo-modules/) or [manually](/bare/installing-expo-modules/#manual-installation). + +## Tools + +[Expo Orbit](https://expo.dev/orbit) to manage and launch builds with one click on macOS and Windows. + +If you want to install and run the build locally on your machine simultaneously, you can use Android Emulator or iOS Simulator. To set them up, see the following: + +- [Android Emulator](/workflow/android-studio-emulator/) +- [iOS Simulator](/workflow/ios-simulator/) (available only on macOS) + +## Next step + +We're ready for this journey after setting up an Expo project locally. In the next chapter, let's learn how to create your first build with EAS Build. + + diff --git a/docs/pages/tutorial/eas/ios-development-build-for-devices.mdx b/docs/pages/tutorial/eas/ios-development-build-for-devices.mdx new file mode 100644 index 0000000000000..7e86ed114e4f1 --- /dev/null +++ b/docs/pages/tutorial/eas/ios-development-build-for-devices.mdx @@ -0,0 +1,218 @@ +--- +title: Create and run a cloud build for iOS device +sidebar_title: iOS development build for devices +description: Learn how to configure a development build for iOS devices using EAS Build. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; + +In this chapter, we'll create a development build that can run on an iOS device with EAS Build. + +Development builds for iOS devices are generated in the **.ipa** format, which is standard for iOS app installations. + +## Prerequisites + +Before we begin, ensure you have: + +- **Apple Developer Account:** This is required to access [necessary credentials](/app-signing/app-credentials/#ios) for signing our app, as each build needs to be signed to verify that the app comes from a trusted source. EAS Build helps manage these credentials. +- **Developer Mode activated on iOS 16 and higher:** Installing development builds on your device requires Developer Mode to be enabled. If this is your first time or if it's currently disabled, see these instructions to [activate Developer Mode](/guides/ios-developer-mode/). + +## Provisioning profile + +To initiate development on an iOS device, we have to: + +- Register the device by creating a new [provisioning profile](/app-signing/app-credentials/#provisioning-profiles). +- Download and install this profile onto the device. + + + +### Register an iOS device + +With EAS CLI, run the command to register a new Apple device: + + + +This command prompts us with the following questions + +- **You're inside the project directory. Would you like to use the** **your-account-name** **account?** Press Y. +- **Apple ID.** For this step, enter your Apple ID. It will then log in to our Apple Developer account. Follow the steps in the terminal window. +- **How would you like to register your devices?** Select **Website** that generates a registration URL that can be opened on the iOS device. + +> **info** **Tip**: If you or your team have multiple devices, you can share the provisioning profile link with those devices for downloading and installing the profile. + + + + + +### Download and install profile + +On a device's web browser, open the link provided in the previous step and tap the **Download Profile button**. + + + +Open the **Settings** app, which prompts us to register our device. + + + +Tap **Install** to register the iOS device. + + + +After the provisioning profile is installed, our device redirects us back to the web browser, displaying a success message indicating the completion of the process. + + + +## Development build for iOS device + + + +### Create + +To create a development build on an iOS device, make sure that under the `build.development` profile: + +- The `developmentClient` is set to `true` in **eas.json**, which is done by the default configuration. +- Then, run the `eas build` command with `ios` as the platform and `development` as the build profile: + + + +> **info** **Tip**: Next time you run `eas build` command, you can also use `-p` to specify the platform. It is short for `--platform`. + +This command prompts us with the following questions when we create the build for the first time: + +- **What would you like your iOS bundle identifier to be?** Press return to select the default value provided for this prompt. This will add [`ios.bundleIdentifier`](/versions/latest/config/app/#package) in **app.json** if it isn't already defined. +- **Log in to our Apple Developer account**. Since we are creating a development build for the first time, it will ask us to **Generate a new Apple Distribution Certificate**. Press Y. +- **Select a device for ad hoc build**. This is the key part, which is why we had to register a provisioning profile before. We can select one or all of our registered devices here and then press return to install that build on those devices later. + +After responding, the build will queue up, and we can track its progress via a provided link by the EAS CLI in the Expo dashboard: + + + + + +The build details page displays the build type, profile, Expo SDK version, app version, build number, last commit hash, and the identity of the developer or account owner who initiated the build. + +In the above image, the current status of the **Build artifact** shows that the build is in progress. Upon completion, this section will offer an option to download the build. The **Logs** outlines every step taken during the iOS build process on EAS Build. For the sake of brevity, we won't explore each step in detail here. To learn more, see [iOS build process](/build-reference/ios-builds/). + + + + + +The `ios.bundleIdentifier` is a unique name of our app. If we publish our app right now, the Apple App Store will use this property and its value to identify our app on the store. + +This notation is defined as `host.owner.app-name`. For example, our example app has `com.owner.stickersmash` where `com.owner` is the domain and `stickermsash` is our app name. + + + + + + + +### Install + +Once the build finishes, the Build artifact section gets updated, indicating that the build is complete: + + + +This section provides the methods available for running the development build on an iOS device: Expo Orbit and Install button. + +[Expo Orbit](https://expo.dev/orbit) allows for seamless installation of the development build on an iOS device. To use this method: + +- Connect our iOS device to our developer machine using USB. +- Open the Orbit menu bar app. +- Select the **Device** in the Orbit app. + + + +- On the Expo dashboard, under **Build artifact**, click the **Open with Orbit**. + +After the build is installed, the Orbit app launches the development build on the device. + + + +The **Install** button in the **Build artifact** section generates a QR code for easy installation: + +- Click **Install** to display a popup with the QR code. + + + +- Scan the QR code with our iOS device's camera to open and tap the link to download the development build on the device. + + + + + + + +### Run + +Start the development server by running the `npx expo start` command from the project directory: + + + +- On the device, tap the app icon to open the development build. + + + +- Use the account syncing feature by ensuring we're logged into both the EAS CLI and development build. As we're already logged into the EAS CLI, the next step is to log in through the UI of your development build. + + + +- Tap **Fetch development servers** and select the server running from the list under Development servers. + + + + + +## Summary + + diff --git a/docs/pages/tutorial/eas/ios-development-build-for-simulators.mdx b/docs/pages/tutorial/eas/ios-development-build-for-simulators.mdx new file mode 100644 index 0000000000000..5a3371d5cc5af --- /dev/null +++ b/docs/pages/tutorial/eas/ios-development-build-for-simulators.mdx @@ -0,0 +1,137 @@ +--- +title: Create and run a cloud build for iOS Simulator +sidebar_title: iOS development build for simulators +description: Learn how to configure a development build for iOS Simulators using EAS Build. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; +import { CODE } from '~/ui/components/Text'; + +In this chapter, we'll create a development build that can run on an iOS Simulator with EAS Build. + +Development builds for iOS Simulators are generated in the **.app** format which is different from iOS devices. + +## Create a simulator build profile in eas.json + +In **eas.json**, add a new build profile called `ios-simulator` with the property [`ios.simulator`](/eas/json/#simulator) property. Set its value `true`: + +{/* prettier-ignore */} +```json eas.json +{ + "build": { + "development": { + /* @hide ... */ /* @end */ + }, + /* @info The simulator property is required for iOS Simulator builds. */ + "ios-simulator": { + "ios": { + "simulator": true + } + } + /* @end */ + } +} +``` + +For a development build, it's necessary to have the `developmentClient` and `distribution` properties defined in the profile. To avoid redundancy, we can extend the `development` profile properties: + +```json eas.json +{ + "ios-simulator": { + /* @info The extends keyword inherits properties from the development profile. */ + "extends": "development", + /* @end */ + "ios": { + "simulator": true + } + } + } +} +``` + +## Development build for iOS Simulator + + + +### Create + +Run the `eas build` command with `ios` as a platform and `ios-simulator` as the build profile: + + + +This command prompts us with the following questions when we create the build for the first time: + +- **What would you like your iOS bundle identifier to be?** Press return to select the default value provided for this prompt. This will add [`ios.bundleIdentifier`](/versions/latest/config/app/#package) in **app.json**. + +After responding to the prompts, our EAS Build is queued, and the EAS CLI provides a link to view build details and track progress on the Expo dashboard: + + + + + +The build details page displays the build type, profile, Expo SDK version, app version, build number, last commit hash, and the identity of the developer or account owner who initiated the build. + +In the above image, the current status of the **Build artifact** shows that the build is in progress. Upon completion, this section will offer an option to download the build. The **Logs** outlines every step taken during the iOS build process on EAS Build. For the sake of brevity, we won't explore each step in detail here. To learn more, see [iOS build process](/build-reference/ios-builds/). + + + + + +The `ios.bundleIdentifier` is a unique name of our app. If we publish our app right now, the Apple App Store will use this property and its value to identify our app on the store. + +This notation is defined as `host.owner.app-name`. For example, our example app has `com.owner.stickersmash` where `com.owner` is the domain and `stickermsash` is our app name. + + + + + + + +### Install + +In the terminal, once the build finishes, EAS CLI prompts us by asking whether we want to run the build on an iOS Simulator. Press Y. + + + + + +You can use [Expo Orbit] to install the development build. From **Build artifact** on the Expo dashboard, click **Open with Expo Orbit** to install the development build on the iOS Simulator. + + + + + + + +### Run + +Start the development server by running the `npx expo start` command from the project directory: + + + +Press i in the terminal window to open the project on the iOS Simulator. + + + +## Summary + + diff --git a/docs/pages/tutorial/eas/ios-production-build.mdx b/docs/pages/tutorial/eas/ios-production-build.mdx new file mode 100644 index 0000000000000..7f9352d1edbc2 --- /dev/null +++ b/docs/pages/tutorial/eas/ios-production-build.mdx @@ -0,0 +1,172 @@ +--- +title: Create a production build for iOS +sidebar_title: iOS production build +description: Learn about the process of creating a production build for iOS and automating the release process. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; +import { CODE } from '~/ui/components/Text'; + +In this chapter, we'll create our example app's production version and submit it for testing using TestFlight. After that, we'll submit them for App Store review to get it on the App Store. + +## Prerequisites + +To publish and distribute an app on the Apple Play Store, we need: + +- **Apple Developer account:** To create one, see [Apple Developer Portal](https://developer.apple.com/account/). +- **Production build profile:** Ensure that a `production` build profile is present in your **eas.json**, which is added by default. + +## Production build for iOS + +A [production iOS build](/build/eas-json/#production-builds) is optimized for Apple's App Store Connect, which allows distributing builds to testers with TestFlight and public end users through the App Store. This build type cannot be side-loaded on a simulator or device and can only be distributed through App Store Connect. + + + +## Create a distribution provisioning profile + +Run the `eas credentials` command in the terminal and then answer the following prompts by EAS CLI: + +- **Select platform** iOS. +- **Which build profile do you want to configure?** Select production. +- **Do you want to log in to your Apple account?** Press Y. This will log in to our Apple Developer account. +- **What do you want to do?** Select **Build credentials** and choose **All: Set up all the required credentials to build your project**. +- Now, it will prompt whether we want to re-use the previous Distribution Certificate. Press Y. +- **Generate a new Apple Provisioning Profile?** Press Y. This will be the provisioning profile for the production app. +- Press any key to exit the EAS CLI. + + + + + +## Create a production build + +To create an iOS production build using the default `production` profile, open your terminal and execute the following command. Since `production` is set as the default profile in the EAS configuration, there is no need to specify it explicitly with the `--profile` flag. + + + +The command will queue the build. Notice on the Expo dashboard that the **Build Number** is auto-incremented. + + + + + +## Submit the app binary to the App Store + +To submit the app binary created from our latest EAS Build, run the [`eas submit`](/submit/introduction/) command: + + + +After running this command, we need to: + +- **Select a build from EAS.** Let's select the latest build ID. +- **Follow the prompt to log in to our Apple account.** When it asks for **Reuse this App Store Connect API Key?** Press Y. + +This will trigger the submission process. + + + + + +## Release an internal testing version + +After the submission process is complete, we'll need to log in to the Apple Developer account from the web browser. + +- Click **[Apps](https://appstoreconnect.apple.com/apps),** and see the app icon. +- Click the app name, and from the navigation tab menu, click **TestFlight**. If the build was just submitted, it may take a few minutes for Apple to process the build before it is available to distribute with TestFlight. +- Click on the **Manage Compliance** link. Since our app doesn't use any encryption, select **None of the algorithms mentioned above**. + +> **info** **Tip:** Next time when creating an app, skip this compliance by adding [`ios.config.usesNonExemptEncryption`](/versions/latest/config/app/#usesnonexemptencryption) in app config and set it to `false` if the app doesn't use any encryption. + +- In App Store Connect, under **Internal Testing**, and create a test group. This will allow us to invite test users. + + + +- Once the group is created, an email will be sent to all the test users. + + + +- In the email, click **View in TestFlight,** accept the invite, and then tap **Install**. + + + +After that, the app will download on our device so that we can test it. + +> **Note**: Similar to internal testing, we can also create a group for inviting external testers using TestFlight. Where internal testing has a limit of 100 users, TestFlight allows sharing a test release version externally with up to 10,000 testers and provides a publicly shareable link. For brevity, we are not going to cover those steps in this tutorial. + + + + + +## Submit the app to the Apple App Store + +To prepare our app for App Store submission, go to the **App Store** tab: + +- Provide metadata details, provide screenshots as per Apple's guidelines and also fill details under **General**. + + + +- Then, manually select the build. + + + +> **Complete App Store listing**: To prepare the app for store listing, see [Create app store assets](/guides/store-assets/) on how to create screenshots and previews. + +- Once our app is ready, click on **Submit to App Review**. After that, Apple will review our app, and if approved, the app will be available on the App Store. + + + + + + + +## Automated submissions + +For future releases, we can streamline the process by combining build creation and App Store submission into a single step by using the [`--auto-submit`](/build/automate-submissions/) flag with `eas build`: + + + + + +## Summary + + + We successfully created a production-ready iOS build, discussed distribution using TestFlight + and Apple App Store using eas submit, and automated the release process with the{' '} + --auto-submit. + + } + nextChapterDescription="In the next chapter, learn how to use the EAS Update to send OTA updates and share previews with our team." + nextChapterTitle="Share previews with your team" + nextChapterLink="/tutorial/eas/team-development/" +/> diff --git a/docs/pages/tutorial/eas/manage-app-versions.mdx b/docs/pages/tutorial/eas/manage-app-versions.mdx new file mode 100644 index 0000000000000..3cdc281f5b0b2 --- /dev/null +++ b/docs/pages/tutorial/eas/manage-app-versions.mdx @@ -0,0 +1,90 @@ +--- +title: Manage different app versions +sidebar_title: Manage app versions +description: Learn about developer-facing and user-facing app versions and how to manage them automatically. +--- + +import { ProgressTracker } from '~/ui/components/ProgressTracker'; +import { CODE } from '~/ui/components/Text'; + +In this chapter, we'll configure our example app to auto-increment the developer-facing app version. Learning about it will be useful before we dive into production build in the next two chapters. + +## Understanding developer-facing and user-facing app versions + +An app version is composed of two values: + +- Developer-facing value: Represented by [`versionCode`](/versions/latest/config/app/#versioncode) for Android and [`buildNumber`](/versions/latest/config/app/#buildnumber) for iOS. +- User-facing value: Represented by [`version`](/versions/latest/config/app/#version) **app.config.js**. + +Both Google Play Store and Apple App Store rely on developer-facing values to identify each unique build. For example, if we upload an app with the app version `1.0.0 (1)` (which is a combination of developer and user facing values), we cannot submit another build to the app stores with the app version. Submitting builds with duplicate app version numbers results in a failed submission. + +We can manually manage developer-facing values by setting them as `android.versionCode` and `ios.buildNumber` in **app.config.js**. + +```json app.config.js +{ + "ios": { + /* @info */ + "buildNumber": "1" + /* @end */ + /* @hide ... */ /* @end */ + }, + "android": { + /* @info */ + "versionCode": "1" + /* @end */ + } + /* @hide ... */ /* @end */ +} +``` + +We can manually update each value in the above code snippet for every new production release. However, this manual update process can be streamlined to minimize the room for error before submitting a new production build to app stores. We use EAS Build to automate this process in the next section. + +> **Note**: The user-facing version number is not handled by EAS. Instead, we define that in the app store developer portals before submitting our production app for review. + +## Automate app version management with EAS Build + +EAS Build can assist us in automating these values by utilizing the [remote version resource](/build-reference/app-versions/#remote-version-source). This feature automatically increments developer-facing values and keeps track of them whenever a new production release is made. + +In **eas.json**: + +- Add `cli.appVersionSource` and set it to `remote` +- Set [`build.production.autoIncrement`](/eas/json/#autoincrement-1) to `true`: + +{/* prettier-ignore */} +```json eas.json +{ + "cli": { + /* @hide ... */ /* @end */ + /* @info Add appVersionSource and set it to remote. */ + "appVersionSource": "remote" + /* @end */ + }, + "build": { + "production": { + /* @info Set the autoIncrement property to true to automatically increment the versionCode or buildNumber. */ + "autoIncrement": true + /* @end */ + } + } + /* @hide ... */ /* @end */ +} +``` + +When we create a new production build in the next two chapters, the `versionCode` for Android and `buildNumber` for iOS will increment automatically. + +## Summary + + + We successfully explored app versioning differences, addressed the importance of unique app + versions to prevent store rejections, and enabled automated version updates in{' '} + eas.json for production builds. + + } + nextChapterDescription="In the next chapter, learn about the process of creating a production build for Android." + nextChapterTitle="Create a production build for Android" + nextChapterLink="/tutorial/eas/android-production-build/" +/> diff --git a/docs/pages/tutorial/eas/multiple-app-variants.mdx b/docs/pages/tutorial/eas/multiple-app-variants.mdx new file mode 100644 index 0000000000000..3734808e765a1 --- /dev/null +++ b/docs/pages/tutorial/eas/multiple-app-variants.mdx @@ -0,0 +1,190 @@ +--- +title: Configure multiple app variants +sidebar_title: Multiple app variants +description: Learn how to configure app config to install multiple app variants on a single device. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; +import { CODE } from '~/ui/components/Text'; + +In this chapter, we'll configure our project to run multiple build types (development, preview, production) on a single device simultaneously. This setup will allow us to test various stages of our app development without the need to uninstall and reinstall different versions. + +Each variant requires a unique Android Application ID and iOS Bundle Identifier to enable simultaneous installations on one device. Here's how the IDs are set up in our **app.json** file: + +```json app.json +{ + "ios": { + /* @info */ + "bundleIdentifier": "com.yourname.stickersmash" + /* @end */ + /* @hide ... */ /* @end */ + }, + "android": { + /* @info */ + "package": "com.yourname.stickersmash" + /* @end */ + /* @hide ... */ /* @end */ + } +} +``` + + + +## Convert app.json to app.config.js for dynamic configuration + +**app.json** contains app-related configuration in a JSON file. It's static and isn't ideal if we want to use [dynamic values for certain properties](/workflow/configuration/#dynamic-configuration). We're going to add different Android Application IDs and iOS Bundle Identifiers for all build profiles based on [environment variables](/workflow/configuration/#switching-configuration-based-on-the-environment). + +- In the code editor, rename **app.json** to **app.config.js**. +- In **app.config.js**, add environment variables called `IS_DEV` and`IS_PREVIEW` for `development` and `preview` build profiles: + +```js app.config.js +const IS_DEV = process.env.APP_VARIANT === 'development'; +const IS_PREVIEW = process.env.APP_VARIANT === 'preview'; +``` + +- Add two functions that dynamically change the app name, Android Application ID and iOS Bundle Identifier: + +```js app.config.js +const getUniqueIdentifier = () => { + if (IS_DEV) { + return 'com.yourname.stickersmash.dev'; + } + + if (IS_PREVIEW) { + return 'com.yourname.stickersmash.preview'; + } + + return 'com.yourname.stickersmash'; +}; + +const getAppName = () => { + if (IS_DEV) { + return 'StickerSmash (Dev)'; + } + + if (IS_PREVIEW) { + return 'StickerSmash (Preview)'; + } + + return 'StickerSmash: Emoji Stickers'; +}; +``` + +- We'll use `getAppName()` to assign varying `name` values for the app and `getUniqueIdentifier()` to differentiate `android.package` and `ios.bundleIdentifier` for development and preview builds: + +{/* prettier-ignore */} +```js app.config.js +export default { + /* @info Using getAppName() for "name" property */ + name: getAppName(), + /* @end */ + /* @hide ... */ /* @end */ + ios: { + /* @info Using getUniqueIdentifier() for "bundleIdentifier" property */ + bundleIdentifier: getUniqueIdentifier(), + /* @end */ + /* @hide ... */ /* @end */ + }, + android: { + /* @info Using getUniqueIdentifier() for "package" property */ + package: getUniqueIdentifier(), + /* @end */ + /* @hide ... */ /* @end */ + }, +}; +``` + + + + + +## Configure eas.json + +In **eas.json**, add the `APP_VARIANT` environment variable: + +{/* prettier-ignore */} +```json eas.json|collapseHeight=440 +{ + "build": { + "development": { + "developmentClient": true, + "distribution": "internal", + /* @info Add env.APP_VARIANT to access the environment variable for the build profile*/ + "env": { + "APP_VARIANT": "development" + } + /* @end */ + }, + "preview": { + "distribution": "internal", + /* @info Add env.APP_VARIANT to access the environment variable for the build profile*/ + "env": { + "APP_VARIANT": "preview" + } + /* @end */ + } + /* @hide ... */ /* @end */ + } +} +``` + +Running `eas build --profile development` will now set `APP_VARIANT` to `development`. + +> **Note**: Since we changed the Android Application ID and iOS Bundle Identifier, the EAS CLI will prompt us to generate a new Keystore for Android and a new provisioning profile for iOS. To learn more about what these steps include, see the previous chapter for more information. + +Since our `ios-simulator` build profile extends `development`, this configuration is automatically applied for iOS Simulators. + + + + + +## Run development server + +> After builds are complete, follow the same procedure from previous chapters to install them on a device or emulator/simulator. + +Since we're identifying our development build with the `APP_VARIANT` environment variable, we need to pass it to the command when starting the development server. To do this, add a `dev` script in the [`"scripts"`](https://docs.npmjs.com/cli/v10/using-npm/scripts) field of our project's **package.json**: + +```json package.json +{ + "scripts": { + "dev": "APP_VARIANT=development npx expo start" + } +} +``` + +Run the `npm run dev` command to start the development server: + + + +This script will evaluate **app.config.js** locally and load the environment variable for the `development` profile. + +Now, our development build will run on both Android and iOS, displaying the modified app name from **app.config.js**. For example, the below development build is running on an iOS Simulator. See that the app name is **StickerSmash (Dev)**: + + + + + +## Summary + + + We successfully switched to app.config.js for dynamic settings, added + environment variables in eas.json to configure specific build profile, and + learned how to start the development server with a custom package.json{' '} + script. + + } + nextChapterDescription="In the next chapter, learn about what are internal distribution builds, why we need them, and how to create them." + nextChapterTitle="Create and share internal distribution build" + nextChapterLink="/tutorial/eas/internal-distribution-builds/" +/> diff --git a/docs/pages/tutorial/eas/next-steps.mdx b/docs/pages/tutorial/eas/next-steps.mdx new file mode 100644 index 0000000000000..ebbdff5fe129f --- /dev/null +++ b/docs/pages/tutorial/eas/next-steps.mdx @@ -0,0 +1,111 @@ +--- +title: Next steps +description: Learn about the next steps in your journey with EAS. +--- + +import { BoxLink } from '~/ui/components/BoxLink'; +import { + BookOpen02Icon, + BuildIcon, + EasSubmitIcon, + EasMetadataIcon, + LayersTwo02Icon, + DataIcon, +} from '@expo/styleguide-icons'; +import { CODE } from '~/ui/components/Text'; + +Congratulations! You've completed the EAS tutorial and learned about the main features. Now, you have a working [EAS project](https://expo.dev/eas). + +## EAS + +But this is just the beginning. Here are some next steps to continue your journey with EAS: + + + + + + + + + + + See EAS Insights documentation to learn more about how to use expo-insights{' '} + library and get precise usage metrics. + + } + href="/eas-insights/introduction/" +/> + +## eas.json reference + + + +## Custom builds + + + +## Relevant guides + + + + + + + + + +We hope you enjoyed this course. If you have any questions or feedback, don't hesitate to reach out to us on [Discord](https://chat.expo.dev/), or share your experience on [X](https://twitter.com/expo). diff --git a/docs/pages/tutorial/eas/team-development.mdx b/docs/pages/tutorial/eas/team-development.mdx new file mode 100644 index 0000000000000..d53e854964e6b --- /dev/null +++ b/docs/pages/tutorial/eas/team-development.mdx @@ -0,0 +1,183 @@ +--- +title: Share previews with your team +sidebar_title: Share previews +description: Learn how to use the EAS Update to send OTA updates and share previews with a team. +--- + +import { Step } from '~/ui/components/Step'; +import { Terminal } from '~/ui/components/Snippet'; +import ImageSpotlight from '~/components/plugins/ImageSpotlight'; +import { Collapsible } from '~/ui/components/Collapsible'; +import Video from '~/components/plugins/Video'; +import { ProgressTracker } from '~/ui/components/ProgressTracker'; + +Updates generally fix small bugs and push small changes in between app store releases. They allow updating the non-native parts of our example app, such as JavaScript code, styling, and images. + +In this chapter, we'll use [EAS Update](/eas-update/introduction/) to share changes with our team. This will help [us and our team quickly share previews](/review/overview/) of the change. + + + +## Install expo-updates library + +To initialize our project and send an update, we need to use the [`expo-updates`](/versions/latest/sdk/updates/) library. Run the following command to install it: + + + + + + + +## Configure EAS Update + +To initialize our project with EAS Update, we need to follow these steps: + +- Since we are using dynamic **app.config.js** for our app's configuration, adding [`updates`](/versions/latest/config/app/#updates) and [`runtimeVersion`](/eas-update/runtime-versions/#setting-runtimeversion) properties are required to make our project compatible with EAS Update. Run the following command to obtain these properties and their values from EAS and manually copy them to **app.config.js**: + + + + + +If a project doesn't use dynamic app config (uses **app.json** instead of **app.config.js**), the above command will configure our app to be compatible with EAS Update and add the right properties to **app.json** and **eas.json**. + + + +- Re-run `eas update:configure` to continue with the setup process. A [`channel`](/eas/json/#channel) should be added to every build profile in **eas.json**: + +{/* prettier-ignore */} +```json eas.json +{ + "build": { + "development": { + /* @hide ... */ /* @end */ + /* @info */ + "channel": "development" + /* @end */ + }, + "ios-simulator": { + /* @hide ... */ /* @end */ + }, + "preview": { + /* @hide ... */ /* @end */ + /* @info */ + "channel": "preview" + /* @end */ + }, + "production": { + /* @hide ... */ /* @end */ + /* @info */ + "channel": "production" + /* @end */ + } + } + /* @hide ... */ /* @end */ +} +``` + +> **info** Notice that the `eas update:configure` command adds the `channel` to every build profile in **eas.json**. However, our `ios-simulator` profile extends the `development` profile and having a separate `channel` doesn't make sense. We can safely remove `ios-simulator.channel` from the above configuration. + + + +[Channels](/eas-update/how-it-works/#conceptual-overview) are used to group builds together. If we have an Android and iOS build, both on the app store, we can give them both a channel of production. Later, we can tell EAS Update to target the production channel, so our update will affect all builds with a production channel. + + + + + + + +## Create a development build + +We need to create a new development build since our last build doesn't contain the `expo-updates` library. Run the following command: + + + +> We are using a development build for Android devices to demonstrate updates. However, we can use `--platform all` or `--platform ios` to create a build for both platforms or just for iOS. + +After the new version of the development build is created, make sure to install it on a device. + + + + + +## Modify the JavaScript code of the app + +Let's modify our example app's JavaScript code. If you are not using [Sticker Smash app](/tutorial/eas/introduction/#prerequisites), you can modify any piece of your code to see the changes in the app. + +We'll modify the text of the first button in our example app that says **Choose a photo** to **Select a photo**. + +```jsx App.js + + )} + + ); + } + return (
{!shouldSkipTitle(route, parentRoute) && title && ( @@ -99,6 +167,8 @@ function getIconElement(iconName?: string) { return PlanEnterpriseIcon; case 'Get started': return HandWaveIcon; + case 'EAS tutorial': + return PlanEnterpriseIcon; default: return undefined; } diff --git a/docs/ui/components/Sidebar/SidebarHead.tsx b/docs/ui/components/Sidebar/SidebarHead.tsx index 1d22881caeef0..39d03e4e7b2d3 100644 --- a/docs/ui/components/Sidebar/SidebarHead.tsx +++ b/docs/ui/components/Sidebar/SidebarHead.tsx @@ -56,7 +56,7 @@ export const SidebarHead = ({ sidebarActiveGroup }: SidebarHeadProps) => { isActive={sidebarActiveGroup === 'reference'} />