Skip to main content

Upgrading to v3

v3 moves the library to Expo SDK 58 and React Native 0.88, and changes how an iOS app with CarPlay or Siri starts. The JavaScript API is unchanged.

Requirements​

v3
ExpoSDK 58 or later
React Native0.88 or later
React19.3 or later
@expo/config-plugins (optional peer)58 or later

On Expo SDK 58 and later, use version 3 (3.0.0 or later). Expo SDK 58 starts React Native from its scene delegate when a window connects, and its app delegate no longer creates a window. Version 2's CarPlay scene setup takes the phone window's content from the app delegate's window, so it does not work on SDK 58, and version 2 is not supported on SDK 58 in any configuration. Version 3 is built for SDK 58's start-up and, with the carplay or siri option, also starts JavaScript for CarPlay and Siri when no phone window is open (see WindowApplicationSceneDelegate is removed).

For Expo SDK 57 and earlier, or React Native older than 0.88, stay on react-native-queue-player 2 (2.0.4-rc.6), the last release for those versions (tested with Expo SDK 57 and React Native 0.86). It is a prerelease, so install it by exact version (@2 resolves to an earlier 2.x release):

npm install react-native-queue-player@2.0.4-rc.6

The config plugin stops on an Expo SDK older than 58 (for example at prebuild):

[react-native-queue-player] Version 3 requires Expo SDK 58 or later. For Expo SDK 57 and earlier, use react-native-queue-player 2 (2.0.4-rc.6).

Run npx expo prebuild --clean after updating​

npx expo prebuild --clean

A prebuild without --clean applies the plugin on top of the native files that are already there, and does not remove what an earlier version or an earlier option wrote (Expo: config plugins and mods). A v2 scene manifest left in Info.plist points the phone scene at a class v3 no longer ships.

The same applies when you change the carplay, siri or chromecast options later: run npx expo prebuild --clean, so code an option no longer needs is removed.

WindowApplicationSceneDelegate is removed​

v2 replaced the app's scene manifest and pointed the phone scene at the library's WindowApplicationSceneDelegate. Expo SDK 58's template has its own SceneDelegate, which creates the window and starts React Native, so v3 keeps the template's phone scene entry and adds to it:

  • With carplay or siri, UIApplicationSupportsMultipleScenes is set to true. Siri only calls the in-app intent handler (application(_:handlerFor:)) in apps that support multiple scenes, and CarPlay runs as a second scene beside the phone.
  • With carplay, the CarPlay scene role (CPTemplateApplicationSceneSessionRoleApplication, delegate CarPlaySceneDelegate) is added.
  • With carplay or siri, the plugin adds code to the generated AppDelegate.swift and SceneDelegate.swift, described in the CarPlay guide.

If your app has its own config plugin that overrides scene(_:willConnectTo:options:), sceneDidDisconnect, sceneDidBecomeActive, sceneWillResignActive, sceneWillEnterForeground or sceneDidEnterBackground in SceneDelegate.swift, prebuild stops with an error naming the method: with carplay or siri on, react-native-queue-player overrides those six.

Bare React Native apps set this up by hand; see Bare React Native.

Behaviour changes​

  • JavaScript starts for CarPlay and Siri without the phone UI. When CarPlay connects or Siri asks for the play-media handler and the app has no phone window, React Native starts in a window that is not on screen. Opening the phone app later moves that same React root into the phone window, so the app does not remount and playback continues.
  • One React root. A second phone window (iPad "New Window", for example) is refused and the existing window is brought forward. A link or activity that opened the refused window is delivered to the running app. iPad still offers "New Window" (Siri and CarPlay need multiple scenes); the user sees an empty window open and close before the existing window returns. Version 2 did not limit phone windows; a second window saved under version 2 and restored by iPadOS is now refused.
  • iOS 26 deployment target. Apps whose deployment target is iOS 26 or later see one UIWindow(frame:) deprecation warning in the generated AppDelegate.swift, from the window used for a CarPlay or Siri start. UIKit has no non-deprecated UIWindow initialiser that takes no window scene, and this start has no scene to pass.
  • Dev-client Debug builds start through the dev launcher, which waits for Metro. A launch from CarPlay or Siri without the phone app runs your JavaScript only once Metro answers. Release and TestFlight builds are not affected.

See the CarPlay guide's notes for the limits that apply to a launch from CarPlay or Siri (initialProperties, Appearance.setColorScheme, expo-updates).

Android​

The library builds with Android Gradle Plugin 9.2.1 and Kotlin 2.2.0, matching React Native 0.88, and its default compileSdk, used when the app sets none, is 37. minSdk stays at 24.