diff --git a/docs/package.json b/docs/package.json index b09d6da5de984..c189312d9caff 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,6 +1,7 @@ { "name": "expo-docs", "version": "48.0.0", + "betaVersion": "49.0.0", "private": true, "type": "module", "scripts": { diff --git a/docs/pages/versions/v49.0.0/config/app.mdx b/docs/pages/versions/v49.0.0/config/app.mdx new file mode 100644 index 0000000000000..20712b38476f3 --- /dev/null +++ b/docs/pages/versions/v49.0.0/config/app.mdx @@ -0,0 +1,17 @@ +--- +title: app.json / app.config.js +maxHeadingDepth: 5 +--- + +{/* Hi! If you found an issue within the description of the manifest properties, please create a GitHub issue. */} + +import AppConfigSchemaPropertiesTable from '~/components/plugins/AppConfigSchemaPropertiesTable'; +import schema from '~/public/static/schemas/unversioned/app-config-schema.json'; + +The following is a list of properties that are available for you under the `"expo"` key in **app.json** or **app.config.json**. These properties can be passed to the top level object of **app.config.js** or **app.config.ts**. + +For more general information on app configuration, such as the differences between the various app configuration files, see [Configuration with app.json/app.config.js](/workflow/configuration/). + +## Properties + + diff --git a/docs/pages/versions/v49.0.0/config/metro.mdx b/docs/pages/versions/v49.0.0/config/metro.mdx new file mode 100644 index 0000000000000..745dd47518599 --- /dev/null +++ b/docs/pages/versions/v49.0.0/config/metro.mdx @@ -0,0 +1,479 @@ +--- +title: metro.config.js +--- + +import { Terminal } from '~/ui/components/Snippet'; +import { FileTree } from '~/ui/components/FileTree'; + +See more information about **metro.config.js** in the [customizing Metro guide](/guides/customizing-metro/). + +## Environment variables + +> For SDK 49 and above + +Environment variables can be loaded using **.env** files. These files are loaded according to the [standard **.env** file resolution](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use). + +If you are migrating an older project to SDK 49 or above, then you should ignore local env files by adding the following to your **.gitignore**: + +```sh .gitignore +# local env files +.env*.local +``` + +### Client environment variables + +Environment variables prefixed with `EXPO_PUBLIC_` will be exposed to the app at build-time. For example, `EXPO_PUBLIC_API_KEY` will be available as `process.env.EXPO_PUBLIC_API_KEY`. + +Environment variables will not be inlined in code inside of **node_modules**. + +For security purposes, client environment variables are inlined in the bundle, which means that `process.env` is not an iterable object, and you cannot dynamically access environment variables. Every variable must be referenced as a static property in order for it to be inlined. For example, the expression `process.env.EXPO_PUBLIC_KEY` will be rewritten and `process.env[‘EXPO_PUBLIC_KEY’]` will not. + +- Client environment variables should not contain secrets as they will be viewable in plain-text format in the production binary. +- Use client environment variables for partially protected values, such as public API keys you don't want to commit to Git or hard-code in your app and that may change depending on the environment. +- Expo environment variables can be updated while the development server (`npx expo start`) is running, without restarting or clearing the bundler cache — however, you'll need to modify and save an included source file to see the updates. You must also perform a client reload, as environment variables do not support Fast Refresh. + +{/* TODO: Usage in EAS */} + +## CSS + +> Available in SDK 49 and higher. + +> **info** CSS support is under development and currently only works on web. + +Expo supports CSS in your project. You can import CSS files from any component. CSS Modules are also supported. To enable CSS, configure your `metro.config.js` as follows, setting `isCSSEnabled` to `true`: + +```js metro.config.js +const { getDefaultConfig } = require('expo/metro-config'); + +/** @type {import('expo/metro-config').MetroConfig} */ +const config = getDefaultConfig(__dirname, { + // Enable CSS support. + isCSSEnabled: true, +}); + +module.exports = config; +``` + +Now you'll need to clear the Metro cache and restart the development server: + + + +Ensure you don't have a custom Metro transformer that processes CSS files. If you do, you'll need to remove it. + +### Global CSS + +> Warning: Global styles are web-only, usage will cause your application to diverge visually on native. + +You can import a CSS file from any component. The CSS will be applied to the entire page. + +Here, we'll define a global style for the class name `.container`: + +```css styles.css +.container { + background-color: red; +} +``` + +We can then use the class name in our component by importing the stylesheet and using `.container`: + +```js App.js +import './styles.css'; +import { View } from 'react-native'; + +export default function App() { + return ( + <> + {/* Use `className` to assign the style with React DOM components. */} +
Hello World
+ + {/* Use `style` with the following syntax to append class names in React Native for web. */} + + Hello World + + + ); +} +``` + +You can also import stylesheets that are vendored in libraries, just like you would any node module: + +```js index.js +// Applies the styles app-wide. +import 'emoji-mart/css/emoji-mart.css'; +``` + +- On native, all global stylesheets are automatically ignored. +- Hot reloading is supported for global stylesheets, simply save the file and the changes will be applied. + +### CSS Modules + +> CSS Modules for native are under development and currently only work on web. + +CSS Modules are a way to scope CSS to a specific component. This is useful for avoiding naming collisions and for ensuring that styles are only applied to the intended component. + +In Expo, CSS Modules are defined by creating a file with the `.module.css` extension. The file can be imported from any component. The exported value is an object with the class names as keys and the web-only scoped names as the values. The import `unstable_styles` can be used to access `react-native-web`-safe styles. + +CSS Modules support platform extensions to allow you to define different styles for different platforms. For example, you can define a `module.ios.css` and `module.android.css` file to define styles for iOS and Android respectively. You'll need to import without the extension, for example: + +```diff App.js +// Importing `./App.module.ios.css`: +- import styles from './App.module.css'; ++ import styles from './App.module'; +``` + +Flipping the extension, e.g. `App.ios.module.css` will not work and result in a universal module named `App.ios.module`. + +> You cannot pass styles to the `className` prop of a React Native or React Native for web component. Instead, you must use the `style` prop. + +```js App.js +import styles, { unstable_styles } from './App.module.css'; + +export default function Page() { + return ( + <> + + Hello World + + Hello World + {/* Web-only usage: */} +

Hello World

+ + ); +} +``` + +```css App.module.css +.text { + color: red; +} +``` + +- On web, all CSS values are available. CSS is not processed or auto-prefixed like it is with the React Native Web `StyleSheet` API. You can use `postcss.config.js` to autoprefix your CSS. +- CSS Modules use [lightningcss](https://github.com/parcel-bundler/lightningcss) under the hood, check [the issues](https://github.com/parcel-bundler/lightningcss/issues) for unsupported features. + +### PostCSS + +> Changing the Post CSS or `browserslist` config will require you to clear the Metro cache: `npx expo start --clear` | `npx expo export --clear`. + +[PostCSS](https://github.com/postcss/postcss) can be customized by adding a `postcss.config.json` file to the root of your project. This file should export a function that returns a PostCSS configuration object. For example: + +```json postcss.config.json +{ + "plugins": { + "autoprefixer": {} + } +} +``` + +Both `postcss.config.json` and `postcss.config.js` are supported, but `postcss.config.json` enables better caching. + +### SASS + +Expo Metro has _partial_ support for SCSS/SASS. + +To setup, install the `sass` package in your project: + + + +Then, ensure [CSS is setup](#css) in the `metro.config.js` file. + +- When `sass` is installed, then modules without extensions will be resolved in the following order: `scss`, `sass`, `css`. +- Only use the intended syntax with `sass` files. +- Importing other files from inside a scss/sass file is not currently supported. + +### Tailwind + +> **info** Tailwind does not support native platforms, this is web-only. + +[Tailwind](https://tailwindcss.com/) can be used with Metro for web. However, due to the advanced caching system in Metro, the setup is a little different from the default Tailwind setup. The following files are modified: + + + +To setup, install the `tailwindcss` package in your project: + + + +In your **app.json** ensure the project is using Metro for web: + +```json app.json +{ + "expo": { + "web": { + "bundler": "metro" + } + } +} +``` + +Create **global.css** in your project: + +```css global.css +/* This file adds the requisite utility classes for Tailwind to work. */ +@tailwind base; +@tailwind components; +@tailwind utilities; +``` + +Create **tailwind.config.js** in your project: + +```js tailwind.config.js +/** @type {import('tailwindcss').Config} */ +module.exports = { + content: [ + // Ensure this points to your source code... + './app/**/*.{js,tsx,ts,jsx}', + // If you use a `src` folder, add: './src/**/*.{js,tsx,ts,jsx}' + // Do the same with `components`, `hooks`, `styles`, or any other top-level folders... + ], + theme: { + extend: {}, + }, + plugins: [], +}; +``` + +In **metro.config.js**, enable CSS support and run the Tailwind CLI: + +```js metro.config.js +const path = require('path'); +const { getDefaultConfig } = require('expo/metro-config'); +const tailwind = require('tailwindcss/lib/cli/build'); + +module.exports = (async () => { + /** @type {import('expo/metro-config').MetroConfig} */ + const config = getDefaultConfig(__dirname, { + // Enable CSS support. + isCSSEnabled: true, + }); + + // Run Tailwind CLI to generate CSS files. + await tailwind.build({ + '--input': path.relative(__dirname, './global.css'), + '--output': path.resolve(__dirname, 'node_modules/.cache/expo/tailwind/eval.css'), + '--watch': process.env.NODE_ENV === 'development' ? 'always' : false, + '--poll': true, + }); + + return config; +})(); +``` + +In your app main entry file, add the following: + +```js index.js/App.js +// Ensure we import the CSS for Tailwind so it's included in hot module reloads. +const ctx = require.context( + // If this require.context is not inside the root directory (next to the package.json) then adjust this file path + // to resolve correctly. + './node_modules/.cache/expo/tailwind' +); +if (ctx.keys().length) ctx(ctx.keys()[0]); +``` + +#### Tailwind Usage + +You can use Tailwind with React DOM elements as-is: + +```jsx +export default function Page() { + return ( +
+

Welcome to Tailwind

+
+ ); +} +``` + +You can use the `{ $$css: true }` syntax to use Tailwind with React Native web elements: + +```jsx +import { View, Text } from 'react-native'; + +export default function Page() { + return ( + + Welcome to Tailwind + + ); +} +``` + +## Bare workflow setup + +> This guide is versioned and will need to be revisited when upgrading/downgrading Expo. Alternatively, use [Expo Prebuild](/workflow/prebuild) for fully automated setup. + +Projects that don't use [Expo Prebuild](/workflow/prebuild) must configure native files to ensure the Expo Metro config is always used to bundle the project. + +{/* If this isn't done, then features like [aliases](/guides/typescript#path-aliases), [absolute imports](/guides/typescript#absolute-imports), asset hashing, and more will not work. */} + +These modifications are meant to replace `npx react-native bundle` and `npx react-native start` with `npx expo export:embed` and `npx expo start --dev-client` respectively. + +### `metro.config.js` + +Ensure the `metro.config.js` extends `expo/metro-config`: + +```js +const { getDefaultConfig } = require('expo/metro-config'); + +const config = getDefaultConfig(__dirname); + +module.exports = config; +``` + +### `android/app/build.gradle` + +The Android `app/build.gradle` must be configured to use Expo CLI for production bundling. Modify the `react` config object: + +```diff +react { + ... ++ // Use Expo CLI to bundle the app, this ensures the Metro config ++ // works correctly with Expo projects. ++ cliFile = new File(["node", "--print", "require.resolve('@expo/cli')"].execute(null, rootDir).text.trim()) ++ bundleCommand = "export:embed" +} +``` + +### `ios/.xcodeproj/project.pbxproj` + +In your `ios/.xcodeproj/project.pbxproj` file, replace the following scripts: + +#### "Start Packager" + +```diff ++ shellScript = "if [[ -f \"$PODS_ROOT/../.xcode.env\" ]]; then\n source \"$PODS_ROOT/../.xcode.env\"\nfi\nif [[ -f \"$PODS_ROOT/../.xcode.env.local\" ]]; then\n source \"$PODS_ROOT/../.xcode.env.local\"\nfi\n\nexport RCT_METRO_PORT=\"${RCT_METRO_PORT:=8081}\"\necho \"export RCT_METRO_PORT=${RCT_METRO_PORT}\" > `$NODE_BINARY --print \"require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/.packager.env'\"`\nif [ -z \"${RCT_NO_LAUNCH_PACKAGER+xxx}\" ] ; then\n if nc -w 5 -z localhost ${RCT_METRO_PORT} ; then\n if ! curl -s \"http://localhost:${RCT_METRO_PORT}/status\" | grep -q \"packager-status:running\" ; then\n echo \"Port ${RCT_METRO_PORT} already in use, packager is either not running or not running correctly\"\n exit 2\n fi\n else\n open `$NODE_BINARY --print \"require('path').dirname(require.resolve('expo/package.json')) + '/scripts/launchPackager.command'\"` || echo \"Can't start packager automatically\"\n fi\nfi\n"; +``` + +**Alternatively**, in the Xcode project, select the "Start Packager" build phase and add the following modifications: + +```diff ++ if [[ -f "$PODS_ROOT/../.xcode.env" ]]; then ++ source "$PODS_ROOT/../.xcode.env" ++ fi ++ if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then ++ source "$PODS_ROOT/../.xcode.env.local" ++ fi + +export RCT_METRO_PORT="${RCT_METRO_PORT:=8081}" +echo "export RCT_METRO_PORT=${RCT_METRO_PORT}" > `$NODE_BINARY --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/.packager.env'"` +if [ -z "${RCT_NO_LAUNCH_PACKAGER+xxx}" ] ; then + if nc -w 5 -z localhost ${RCT_METRO_PORT} ; then + if ! curl -s "http://localhost:${RCT_METRO_PORT}/status" | grep -q "packager-status:running" ; then + echo "Port ${RCT_METRO_PORT} already in use, packager is either not running or not running correctly" + exit 2 + fi + else +- open `$NODE_BINARY --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/launchPackager.command'"` || echo "Can't start packager automatically" ++ open `$NODE_BINARY --print "require('path').dirname(require.resolve('expo/package.json')) + '/scripts/launchPackager.command'"` || echo "Can't start packager automatically" + fi +fi +``` + +#### "Bundle React Native code and images" + +```diff ++ shellScript = "if [[ -f \"$PODS_ROOT/../.xcode.env\" ]]; then\n source \"$PODS_ROOT/../.xcode.env\"\nfi\nif [[ -f \"$PODS_ROOT/../.xcode.env.local\" ]]; then\n source \"$PODS_ROOT/../.xcode.env.local\"\nfi\n\n# The project root by default is one level up from the ios directory\nexport PROJECT_ROOT=\"$PROJECT_DIR\"/..\n\nif [[ \"$CONFIGURATION\" = *Debug* ]]; then\n export SKIP_BUNDLING=1\nfi\nif [[ -z \"$ENTRY_FILE\" ]]; then\n # Set the entry JS file using the bundler's entry resolution.\n export ENTRY_FILE=\"$(\"$NODE_BINARY\" -e \"require('expo/scripts/resolveAppEntry')\" \"$PROJECT_ROOT\" ios relative | tail -n 1)\"\nfi\n\nif [[ -z \"$CLI_PATH\" ]]; then\n # Use Expo CLI\n export CLI_PATH=\"$(\"$NODE_BINARY\" --print \"require.resolve('@expo/cli')\")\"\nfi\nif [[ -z \"$BUNDLE_COMMAND\" ]]; then\n # Default Expo CLI command for bundling\n export BUNDLE_COMMAND=\"export:embed\"\nfi\n\n`\"$NODE_BINARY\" --print \"require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'\"`\n\n"; +``` + +**Alternatively**, in the Xcode project, select the "Bundle React Native code and images" build phase and add the following modifications: + +```diff +if [[ -f "$PODS_ROOT/../.xcode.env" ]]; then + source "$PODS_ROOT/../.xcode.env" +fi +if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then + source "$PODS_ROOT/../.xcode.env.local" +fi + +# The project root by default is one level up from the ios directory +export PROJECT_ROOT="$PROJECT_DIR"/.. + +if [[ "$CONFIGURATION" = *Debug* ]]; then + export SKIP_BUNDLING=1 +fi ++ if [[ -z "$ENTRY_FILE" ]]; then ++ # Set the entry JS file using the bundler's entry resolution. ++ export ENTRY_FILE="$("$NODE_BINARY" -e "require('expo/scripts/resolveAppEntry')" "$PROJECT_ROOT" ios relative | tail -n 1)" ++ fi + ++ if [[ -z "$CLI_PATH" ]]; then ++ # Use Expo CLI ++ export CLI_PATH="$("$NODE_BINARY" --print "require.resolve('@expo/cli')")" ++ fi ++ if [[ -z "$BUNDLE_COMMAND" ]]; then ++ # Default Expo CLI command for bundling ++ export BUNDLE_COMMAND="export:embed" ++ fi + +`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"` +``` + +> You can set `CLI_PATH`, `BUNDLE_COMMAND`, and `ENTRY_FILE` environment variables to overwrite these defaults. + +### Custom Entry File + +By default, React Native only supports using a root `index.js` file as the entry file (or platform-specific variation like `index.ios.js`). Expo projects allow using any entry file, but this requires addition bare setup. + +#### Development + +Development mode entry files can be enabled by using the [`expo-dev-client`](/clients/introduction.mdx) package. Alternatively you can add the following configuration: + +In the `ios/[project]/AppDelegate.mm` file: + +```diff +- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge +{ +#if DEBUG +- return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"]; ++ return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@".expo/.virtual-metro-entry"]; +#else + return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"]; +#endif +} +``` + +In the `android/app/src/main/java/**/MainApplication.java`: + +```diff +@Override +protected String getJSMainModuleName() { +- return "index"; ++ return ".expo/.virtual-metro-entry"; +} +``` + +#### Production + +In your `ios/.xcodeproj/project.pbxproj` file, replace the `"Bundle React Native code and images"` script to set `$ENTRY_FILE` according using Metro: + +```diff ++ shellScript = "if [[ -f \"$PODS_ROOT/../.xcode.env\" ]]; then\n source \"$PODS_ROOT/../.xcode.env\"\nfi\nif [[ -f \"$PODS_ROOT/../.xcode.env.local\" ]]; then\n source \"$PODS_ROOT/../.xcode.env.local\"\nfi\n\n# The project root by default is one level up from the ios directory\nexport PROJECT_ROOT=\"$PROJECT_DIR\"/..\n\nif [[ \"$CONFIGURATION\" = *Debug* ]]; then\n export SKIP_BUNDLING=1\nfi\nif [[ -z \"$ENTRY_FILE\" ]]; then\n # Set the entry JS file using the bundler's entry resolution.\n export ENTRY_FILE=\"$(\"$NODE_BINARY\" -e \"require('expo/scripts/resolveAppEntry')\" \"$PROJECT_ROOT\" ios relative | tail -n 1)\"\nfi\n\nif [[ -z \"$CLI_PATH\" ]]; then\n # Use Expo CLI\n export CLI_PATH=\"$(\"$NODE_BINARY\" --print \"require.resolve('@expo/cli')\")\"\nfi\nif [[ -z \"$BUNDLE_COMMAND\" ]]; then\n # Default Expo CLI command for bundling\n export BUNDLE_COMMAND=\"export:embed\"\nfi\n\n`\"$NODE_BINARY\" --print \"require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'\"`\n\n"; +``` + +The Android `app/build.gradle` must be configured to use Metro module resolution to find the root entry file. Modify the `react` config object: + +```diff ++ def projectRoot = rootDir.getAbsoluteFile().getParentFile().getAbsolutePath() + +react { ++ entryFile = file(["node", "-e", "require('expo/scripts/resolveAppEntry')", projectRoot, "android", "absolute"].execute(null, rootDir).text.trim()) +} +``` diff --git a/docs/pages/versions/v49.0.0/index.mdx b/docs/pages/versions/v49.0.0/index.mdx new file mode 100644 index 0000000000000..e9a054c8cf71d --- /dev/null +++ b/docs/pages/versions/v49.0.0/index.mdx @@ -0,0 +1,78 @@ +--- +title: Reference +hideTOC: true +--- + +import VersionedRedirectNotification from '~/components/plugins/VersionedRedirectNotification'; +import { Terminal } from '~/ui/components/Snippet'; +import { BoxLink } from '~/ui/components/BoxLink'; +import { CODE } from '~/ui/components/Text'; + + + +The Expo SDK provides access to device and system functionality such as contacts, camera, gyroscope, GPS location, and so on, in the form of packages. You can install any Expo SDK package using the `npx expo install` command. For example, three different packages are installed using the following command: + + + +After installing one or more packages, you can import them into your JavaScript code: + +```javascript +import { Camera } from 'expo-camera'; +import * as Contacts from 'expo-contacts'; +import { Gyroscope } from 'expo-sensors'; +``` + +This allows you to write [`Contacts.getContactsAsync()`](/versions/latest/sdk/contacts#contactsgetcontactsasynccontactquery) and read the contacts from the device, read the gyroscope sensor to detect device movement, or start the phone's camera and take photos. + +## These packages work in bare React Native apps too + +The easiest way to create a bare React Native app with support for the Expo SDK is by running the command: + + + + + Projects that were created with npx react-native init require + additional setup to use the Expo SDK. + + } +/> + + + +## Each Expo SDK version depends on a React Native version + +Every quarter there is a new Expo SDK release that typically updates to the latest stable versions of React Native and React Native Web, and includes a variety of bug fixes, features, and improvements to the Expo SDK. + +| Expo SDK version | React Native version | React Native Web version | +| ---------------- | -------------------- | ------------------------ | +| 48.0.0 | 0.71 | 0.18.12 | +| 47.0.0 | 0.70 | 0.18.9 | +| 46.0.0 | 0.69 | 0.18.7 | +| 45.0.0 | 0.68 | 0.17.7 | +| 44.0.0 | 0.64 | 0.17.1 | + +### Support for other React Native versions + +Packages in the Expo SDK are intended to support the target React Native version for that SDK. Typically, they will not support older versions of React Native, but they may. When a new version of React Native is released, the latest versions of the Expo SDK packages are typically updated to support it. However, this may take weeks or more, depending on the extent of the changes in the release. + +## Support for Android and iOS versions + +Each version of Expo SDK supports a minimum OS version of Android and iOS. For Android, the `compileSdkVersion` is defined which tells the [Gradle](https://developer.android.com/studio/build) which Android SDK version to use to compile the app. This also means that you can use the Android API features included in that SDK version and from the previous versions. + +| Expo SDK version | Android version | `compileSdkVersion` | iOS version | +| ---------------- | --------------- | ------------------- | ----------- | +| 47.0.0 | 5+ | 31 | 13+ | +| 46.0.0 | 5+ | 31 | 12.4+ | +| 45.0.0 | 5+ | 31 | 12+ | +| 44.0.0 | 5+ | 30 | 12+ | diff --git a/docs/pages/versions/v49.0.0/sdk/accelerometer.mdx b/docs/pages/versions/v49.0.0/sdk/accelerometer.mdx new file mode 100644 index 0000000000000..ec94121048ff8 --- /dev/null +++ b/docs/pages/versions/v49.0.0/sdk/accelerometer.mdx @@ -0,0 +1,118 @@ +--- +title: Accelerometer +sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-49/packages/expo-sensors' +packageName: 'expo-sensors' +iconUrl: '/static/images/packages/expo-sensors.png' +--- + +import APISection from '~/components/plugins/APISection'; +import { APIInstallSection } from '~/components/plugins/InstallSection'; +import { SnackInline} from '~/ui/components/Snippet'; + +import PlatformsSection from '~/components/plugins/PlatformsSection'; + +`Accelerometer` from **`expo-sensors`** provides access to the device accelerometer sensor(s) and associated listeners to respond to changes in acceleration in three-dimensional space, meaning any movement or vibration. + + + +## Installation + + + +## Usage + + + +```jsx +import React, { useState, useEffect } from 'react'; +import { StyleSheet, Text, TouchableOpacity, View } from 'react-native'; +import { Accelerometer } from 'expo-sensors'; + +export default function App() { + const [{ x, y, z }, setData] = useState({ + x: 0, + y: 0, + z: 0, + }); + const [subscription, setSubscription] = useState(null); + + const _slow = () => Accelerometer.setUpdateInterval(1000); + const _fast = () => Accelerometer.setUpdateInterval(16); + + const _subscribe = () => { + setSubscription( + Accelerometer.addListener(setData) + ); + }; + + const _unsubscribe = () => { + subscription && subscription.remove(); + setSubscription(null); + }; + + useEffect(() => { + _subscribe(); + return () => _unsubscribe(); + }, []); + + return ( + + Accelerometer: (in gs where 1g = 9.81 m/s^2) + x: {x} + y: {y} + z: {z} + + + {subscription ? 'On' : 'Off'} + + + Slow + + + Fast + + + + ); +} + +/* @hide const styles = StyleSheet.create({ ... }); */ +const styles = StyleSheet.create({ + container: { + flex: 1, + justifyContent: 'center', + paddingHorizontal: 20, + }, + text: { + textAlign: 'center', + }, + buttonContainer: { + flexDirection: 'row', + alignItems: 'stretch', + marginTop: 15, + }, + button: { + flex: 1, + justifyContent: 'center', + alignItems: 'center', + backgroundColor: '#eee', + padding: 10, + }, + middleButton: { + borderLeftWidth: 1, + borderRightWidth: 1, + borderColor: '#ccc', + }, +}); +/* @end */ +``` + + + +## API + +```js +import { Accelerometer } from 'expo-sensors'; +``` + + \ No newline at end of file diff --git a/docs/pages/versions/v49.0.0/sdk/apple-authentication.mdx b/docs/pages/versions/v49.0.0/sdk/apple-authentication.mdx new file mode 100644 index 0000000000000..a3560a4ec8152 --- /dev/null +++ b/docs/pages/versions/v49.0.0/sdk/apple-authentication.mdx @@ -0,0 +1,157 @@ +--- +title: AppleAuthentication +sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-49/packages/expo-apple-authentication' +packageName: 'expo-apple-authentication' +--- + +import { ConfigReactNative, ConfigPluginExample } from '~/components/plugins/ConfigSection'; +import APISection from '~/components/plugins/APISection'; +import { APIInstallSection } from '~/components/plugins/InstallSection'; +import PlatformsSection from '~/components/plugins/PlatformsSection'; +import { SnackInline } from '~/ui/components/Snippet'; + +`expo-apple-authentication` provides Apple authentication for iOS 13+. It does not yet support lower iOS versions, Android, or the web. + +Beginning with iOS 13, any app that includes third-party authentication options **must** provide Apple authentication as an option +in order to comply with App Store Review guidelines. For more information, see Apple authentication on the [Sign In with Apple](https://developer.apple.com/sign-in-with-apple/) website. + + + +## Installation + + + +## Configuration in app.json/app.config.js + +You can configure `expo-apple-authentication` using its built-in [config plugin](/config-plugins/introduction/) if you use config plugins +in your project ([EAS Build](/build/introduction) or `npx expo run:[android|ios]`). +The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. +If your app does **not** use EAS Build, then you'll need to manually configure the package. + + + +> This plugin is included automatically when installed. + +Running [EAS Build](/build/introduction) locally will use [iOS capabilities signing](/build-reference/ios-capabilities) to enable the required capabilities before building. + +```json app.json +{ + "expo": { + "plugins": ["expo-apple-authentication"] + } +} +``` + + + + + +Apps that don't use [EAS Build](/build/introduction) must [manually configure](/build-reference/ios-capabilities#manual-setup) +the **Apple Sign In** capability for their bundle identifier. + +If you enable the **Apple Sign In** capability through the [Apple Developer Console](/build-reference/ios-capabilities#apple-developer-console), +then be sure to add the following entitlements in your **ios/[app]/[app].entitlements** file: + +```xml +com.apple.developer.applesignin + + Default + +``` + +Also be sure to set `CFBundleAllowMixedLocalizations` to `true` in your **ios/[app]/Info.plist** to ensure the sign in button uses the device locale. + + + +## Usage + + + +```jsx +import * as AppleAuthentication from 'expo-apple-authentication'; +import { View, StyleSheet } from 'react-native'; + +export default function App() { + return ( + + { + try { + const credential = await AppleAuthentication.signInAsync({ + requestedScopes: [ + AppleAuthentication.AppleAuthenticationScope.FULL_NAME, + AppleAuthentication.AppleAuthenticationScope.EMAIL, + ], + }); + // signed in + } catch (e) { + if (e.code === 'ERR_REQUEST_CANCELED') { + // handle that the user canceled the sign-in flow + } else { + // handle other errors + } + } + }} + /> + + ); +} + +/* @hide const styles = StyleSheet.create({ ... }); */ +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + button: { + width: 200, + height: 44, + }, +}); +/* @end */ +``` + + + +## Development and Testing + +You can test this library in Expo Go on iOS without following any of the instructions above. +However, you'll need to add the config plugin to use this library if you are using EAS Build. +When you sign into Expo Go, the identifiers and values you receive will likely be different than what you'll receive in standalone apps. + +You can do limited testing of this library on the iOS Simulator. However, not all methods will behave the same as on a device, +so we highly recommend testing on a real device when possible while developing. + +## Verifying the Response from Apple + +Apple's response includes a signed JWT with information about the user. To ensure that the response came from Apple, +you can cryptographically verify the signature with Apple's public key, which is published at https://appleid.apple.com/auth/keys. +This process is not specific to Expo. + +## API + +```js +import * as AppleAuthentication from 'expo-apple-authentication'; +``` + + + +## Error Codes + +Most of the error codes matches the official [Apple Authorization errors](https://developer.apple.com/documentation/authenticationservices/asauthorizationerror/code). + +| Code | Description | +| --------------------------- | -------------------------------------------------------------------------------------- | +| ERR_INVALID_OPERATION | An invalid authorization operation has been performed. | +| ERR_INVALID_RESPONSE | The authorization request received an invalid response. | +| ERR_INVALID_SCOPE | An invalid [`AppleAuthenticationScope`](#appleauthenticationscope) was passed in. | +| ERR_REQUEST_CANCELED | The user canceled the authorization attempt. | +| ERR_REQUEST_FAILED | The authorization attempt failed. See the error message for an additional information. | +| ERR_REQUEST_NOT_HANDLED | The authorization request wasn’t correctly handled. | +| ERR_REQUEST_NOT_INTERACTIVE | The authorization request isn’t interactive. | +| ERR_REQUEST_UNKNOWN | The authorization attempt failed for an unknown reason. | diff --git a/docs/pages/versions/v49.0.0/sdk/application.mdx b/docs/pages/versions/v49.0.0/sdk/application.mdx new file mode 100644 index 0000000000000..8a71dbf13597b --- /dev/null +++ b/docs/pages/versions/v49.0.0/sdk/application.mdx @@ -0,0 +1,36 @@ +--- +title: Application +sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-49/packages/expo-application' +packageName: 'expo-application' +--- + +import APISection from '~/components/plugins/APISection'; +import { APIInstallSection } from '~/components/plugins/InstallSection'; +import PlatformsSection from '~/components/plugins/PlatformsSection'; + +**`expo-application`** provides useful information about the native application, itself, such as the ID, app name, and build version. + + + +## Installation + + + +## API + +```js +import * as Application from 'expo-application'; +``` + + + +## Error Codes + +| Code | Description | +| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ERR_APPLICATION_PACKAGE_NAME_NOT_FOUND | Error code thrown by `getInstallationTimeAsync` and `getLastUpdateTimeAsync`. This may be thrown if the package information or package name could not be retrieved. | +| ERR_APPLICATION_INSTALL_REFERRER_UNAVAILABLE | The current Play Store app doesn't provide the installation referrer API, or the Play Store may not be installed. This error code may come up when testing on an AVD that doesn't come with the Play Store pre-installed, such as the Google Pixel 3 and Nexus 6. | +| ERR_APPLICATION_INSTALL_REFERRER_CONNECTION | A connection could not be established to the Google Play Store. | +| ERR_APPLICATION_INSTALL_REFERRER_REMOTE_EXCEPTION | A `RemoteException` was thrown after a connection was established to the Play Store. This may happen if the process hosting the remote object is no longer available, which usually means the process crashed. See https://stackoverflow.com/questions/3156389/android-remoteexceptions-and-services. | +| ERR_APPLICATION_INSTALL_REFERRER | General default case error code for the `getInstallReferrerAsync` method. This error code will be thrown if an exception occurred when getting the install referrer, but the exception was none of the more precise errors. The [`responseCode`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient.InstallReferrerResponse.html) is provided along with the error. | +| ERR_APPLICATION_INSTALL_REFERRER_SERVICE_DISCONNECTED | Connection to the install referrer service was lost. This error is thrown when an attempt was made to connect and set up the install referrer service, but the connection was lost. See the [Android documentation](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerStateListener) for more information. | diff --git a/docs/pages/versions/v49.0.0/sdk/asset.mdx b/docs/pages/versions/v49.0.0/sdk/asset.mdx new file mode 100644 index 0000000000000..c686182a3afe4 --- /dev/null +++ b/docs/pages/versions/v49.0.0/sdk/asset.mdx @@ -0,0 +1,25 @@ +--- +title: Asset +sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-49/packages/expo-asset' +packageName: 'expo-asset' +--- + +import APISection from '~/components/plugins/APISection'; +import { APIInstallSection } from '~/components/plugins/InstallSection'; +import PlatformsSection from '~/components/plugins/PlatformsSection'; + +**`expo-asset`** provides an interface to Expo's asset system. An asset is any file that lives alongside the source code of your app that the app needs at runtime. Examples include images, fonts, and sounds. Expo's asset system integrates with React Native's, so that you can refer to files with `require('path/to/file')`. This is how you refer to static image files in React Native for use in an `Image` component, for example. Check out React Native's [documentation on static image resources](https://reactnative.dev/docs/images#static-image-resources) for more information. This method of referring to static image resources works out of the box with Expo. + + + +## Installation + + + +## API + +```js +import { Asset } from 'expo-asset'; +``` + + diff --git a/docs/pages/versions/v49.0.0/sdk/async-storage.mdx b/docs/pages/versions/v49.0.0/sdk/async-storage.mdx new file mode 100644 index 0000000000000..3c085f52b9fb0 --- /dev/null +++ b/docs/pages/versions/v49.0.0/sdk/async-storage.mdx @@ -0,0 +1,20 @@ +--- +title: AsyncStorage +sourceCodeUrl: 'https://github.com/react-native-async-storage/async-storage' +packageName: '@react-native-async-storage/async-storage' +--- + +import { APIInstallSection } from '~/components/plugins/InstallSection'; +import PlatformsSection from '~/components/plugins/PlatformsSection'; + +An asynchronous, unencrypted, persistent, key-value storage API. + + + +## Installation + + + +## Usage + +See full documentation at [https://react-native-async-storage.github.io/async-storage/](https://react-native-async-storage.github.io/async-storage/docs/usage). diff --git a/docs/pages/versions/v49.0.0/sdk/audio.mdx b/docs/pages/versions/v49.0.0/sdk/audio.mdx new file mode 100644 index 0000000000000..ad3d1590bb248 --- /dev/null +++ b/docs/pages/versions/v49.0.0/sdk/audio.mdx @@ -0,0 +1,198 @@ +--- +title: Audio +sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-49/packages/expo-av' +packageName: 'expo-av' +iconUrl: '/static/images/packages/expo-av.png' +--- + +import { APIInstallSection } from '~/components/plugins/InstallSection'; +import PlatformsSection from '~/components/plugins/PlatformsSection'; +import { SnackInline} from '~/ui/components/Snippet'; +import APISection from '~/components/plugins/APISection'; +import { PlatformTags } from '~/ui/components/Tag'; + +**`expo-av`** allows you to implement audio playback and recording in your app. + +Note that audio automatically stops if headphones / bluetooth audio devices are disconnected. + +Try the [playlist example app](https://expo.dev/@documentation/playlist-example) (source code is [on GitHub](https://github.com/expo/playlist-example)) to see an example usage of the media playback API, and the [recording example app](https://expo.dev/@documentation/record) (source code is [on GitHub](https://github.com/expo/audio-recording-example)) to see an example usage of the recording API. + + + +## Installation + + + +## Usage + +### Playing sounds + + + +```jsx +import * as React from 'react'; +import { Text, View, StyleSheet, Button } from 'react-native'; +import { Audio } from 'expo-av'; + +export default function App() { + const [sound, setSound] = React.useState(); + + async function playSound() { + console.log('Loading Sound'); + /* @info */ const { sound } = await Audio.Sound.createAsync( + /* @end */ require('./assets/Hello.mp3') + ); + setSound(sound); + + console.log('Playing Sound'); + await /* @info */ sound.playAsync(); /* @end */ + } + + React.useEffect(() => { + return sound + ? () => { + console.log('Unloading Sound'); + /* @info Always unload the Sound after using it to prevent memory leaks.*/ sound.unloadAsync(); /* @end */ + } + : undefined; + }, [sound]); + + return ( + +