DOCSEARCHbyAlgolia
Submit Docs

expo.fyi Documentation

repository·main·Indexed 22 days ago

https://github.com/expo/fyi

A URL shortening service that links to markdown files within the expo/fyi GitHub repository to provide clean, shareable URLs for developer documentation and terminology. This repository also contains technical guides on Android 16KB page size compatibility, AAPT2 build errors, PNG optimization, Android app size estimation, and migrating existing apps to Expo tools.

Tokens
45.5K
Snippets
130
Records
258
Agent score
74%

What's inside expo-fyi

  1. Overview of EAS Update

    main
    EAS Update is a hosted service designed for projects using the expo-updates library. It allows you to push quick fixes and small bug fixes to your users without requiring a full app store submission. It works by swapping out the non-native parts of your application—such as JavaScript code, styles, and images—with a new update package.

  3. Use the `extra` object for arbitrary fields in app config

    main
    When migrating to a root-level configuration in app.json, you should not place non-standard or custom properties directly at the root. Instead, use the extra object to store arbitrary fields that are not part of the standard Expo configuration schema.

  4. Understand the default EAS CLI VCS integration

    main

    By default, EAS CLI integrates with Git to identify your project root and metadata (like branch and commit hash).

    Key behaviors of the default workflow:

    • No commits required: You do not need to commit changes before running a build.
    • Working directory upload: EAS CLI uploads a copy of your current working directory to EAS Build.
    • Ignore rules: It respects .gitignore files or .easignore files.
    • Metadata: It uses git to find project metadata, but does not upload the .git directory itself.

  5. Understand Expo SDK and React Native versioning in the managed workflow

    main

    In the Expo managed workflow, every version of the Expo SDK is tied to one specific version of React Native. For example, Expo SDK 38 uses React Native 0.62.2. This tight coupling ensures stability across the JS interpreter, the JS–native bridge, debugging tools, view components, and the bundler.

    Key release patterns to note:

    • Expo SDK Releases: Occur quarterly (end of March, June, September, and December).
    • React Native Releases: Do not follow a time-based schedule and can occur at any time.
    • Compatibility Gap: There is often a period of adjustment after a React Native release while the ecosystem (including third-party libraries and React Native for Web) catches up and initial bugs are resolved via React Native patch releases.

  6. Understand why dependency issues occur in Expo

    main

    Dependency issues in Expo typically manifest as errors during native builds, app bundling/exporting, or at runtime. There are four primary causes:

    1. SDK Incompatibility: App dependencies have version ranges incompatible with the installed Expo SDK.
    2. Incompatible Peer Dependencies: Your dependencies depend on incompatible versions of the same underlying packages.
    3. Package Manager State: The package manager has duplicated versions in the tree or is in an unclean state.
    4. Monorepo Conflicts: In monorepos (Bun, npm, pnpm, or Yarn), different workspaces specify duplicate version ranges that cannot be easily hoisted.

    Types of failures

    • Runtime issues: Occur when a package is designed as a singleton (e.g., react). If multiple versions are bundled, the internal state/values may not be shared correctly across the app.
    • Native linking issues: Occur because of Expo Autolinking. While Node.js resolution allows duplicate JavaScript packages, native builds can only compile one version of any native module. Duplicate JavaScript versions of native modules can cause conflicts during the native compilation process.

  7. Subscribe to application events using Expo Modules API

    main

    To hook into critical application lifecycle events (such as onCreate on Android or applicationDidFinishLaunching on iOS) for third-party SDK setup, use the Expo Modules API instead of modifying native project files directly via config plugins.

    This is achieved through two primary mechanisms:

    • Android lifecycle listeners: For hooking into Android-specific lifecycle events.
    • iOS AppDelegate subscribers: For hooking into iOS AppDelegate events.

    These are collectively referred to as Subscribers. Using Subscribers is more robust than config plugins because they compose well with multiple listeners and are not broken by changes in the underlying native language (e.g., the migration of AppDelegate from Objective-C to Swift in SDK 53).

  8. Replace LegacyNotifications listener methods

    main

    The single addListener method in LegacyNotifications is split into two distinct listeners in expo-notifications to better handle different notification states:

    1. Notifications.addNotificationReceivedListener(): Triggered when a notification is received while the app is in the foreground.
    2. Notifications.addNotificationResponseReceivedListener(): Triggered when a user interacts with a notification (e.g., tapping it or selecting a category action).

    Recommended Hook: For handling user interactions, use the useLastNotificationResponse hook instead of manual listeners.

  10. Understand how EAS CLI packages project files

    main

    By default, EAS CLI collects and compresses project files into an archive for upload. The packaging behavior depends on whether you are using Git or have opted out.

    Default Behavior (Git-based)

    EAS CLI approximates a git clone --depth 1 to allow building with a "dirty" working tree (uncommitted changes).

    • Included: All files from the git root, including submodule content as it exists in your working directory.
    • Excluded: .git, node_modules, and files matched by .gitignore or .easignore.
    • Limitations:
      • Multiple .gitignore files are applied in isolation from the root, which can lead to unexpected exclusion patterns.
      • The .git directory is not uploaded, which may break tools requiring Git metadata (e.g., Sentry needing commit hashes).
      • Sensitive files managed by git-crypt are uploaded in their unencrypted state as they exist in your working directory.

    Strict Git Mode (requireCommit: true)

    If you set "requireCommit": true in the cli section of your eas.json, EAS CLI performs a real git clone --depth 1.

    • The uploaded project is an exact replica of the Git state (including branch and commit hash).
    • Note: .easignore is not supported when requireCommit is enabled.
    {
  "cli": {
    "requireCommit": true
  }
}

  11. How EAS Update rollouts work

    main

    An EAS Update rollout allows you to distribute a specific update to a percentage of your users on a given channel.

    For example, if your channel is currently mapped to Branch A (with Update A), and you create a rollout to Branch B (with Update B), a defined percentage of your users will receive Update B, while the remaining users will continue to receive Update A.

  12. Determine when a new React Native version will be supported by Expo

    main

    Expo does not guarantee immediate support for the latest React Native release. Instead, the Expo team evaluates several factors before updating an SDK to a new React Native version to ensure stability and minimize regressions for managed workflow users.

    Support for a new React Native version depends on:

    1. The next Expo SDK release cycle: This is the earliest possible window for an update.
    2. Ecosystem readiness: Whether third-party libraries, React Native for Web, and significant open issues have stabilized.
    3. React Native stability: Whether sufficient patch releases have been issued to resolve initial regressions.
    4. Importance and Effort: The necessity of the update for users versus the amount of work required to maintain Expo stability.
    5. Team Bandwidth: Availability of the Expo team, which may be prioritized toward other critical tasks like supporting new iOS or Android releases.