expo-detect-carplay

Expo native module for observing CarPlay and Android Auto connection state on iOS and Android, including persistent monitoring, notifications, event logging, native API forwarding, and optional background-geolocation integration.

| Platform | Detection | Background behavior | | -------- | -------------------------------------------- | --------------------------------------------------- | | Android | AndroidX CarConnection | Connected-device foreground service | | iOS | Car audio route; optional Driving Task scene | Foreground observation with optional location wakes | | Web | Inert fallback | Monitoring methods are no-ops |

Important constraints

• Native code is required. Expo Go is not supported.
• Add the bundled config plugin before creating a development build.
• Basic iOS detection does not require a CarPlay entitlement, but audio-route observation cannot launch a terminated app.
• Enable ios.carplayDrivingTask only after Apple grants the entitlement and the provisioning profile contains it.
• The background-geolocation bridge is optional and requires react-native-background-geolocation in the consuming app.

Install

npx expo install expo-detect-carplay

Add the config plugin:

{
  "expo": {
    "plugins": ["expo-detect-carplay"]
  }
}

Rebuild the native application after adding or changing the plugin:

npx expo prebuild
npx expo run:android
# or: npx expo run:ios

See Getting started for platform permissions and the complete installation path.

Monitor vehicle connections

import { Platform } from 'react-native';
import { ExpoDetectCarplay } from 'expo-detect-carplay';

if (Platform.OS === 'android') {
  const granted = await ExpoDetectCarplay.requestPermissionsAsync();
  if (!granted) {
    throw new Error('Vehicle connection permissions were not granted');
  }
}

const connected = ExpoDetectCarplay.addListener('onCarPlayConnected', (event) =>
  console.log('connected', event.transport)
);
const disconnected = ExpoDetectCarplay.addListener('onCarPlayDisconnected', (event) =>
  console.log('disconnected', event.reason)
);

await ExpoDetectCarplay.startCarPlayMonitoring();
const status = ExpoDetectCarplay.getCarPlayConnectionStatus();

// When persistent monitoring is no longer wanted:
await ExpoDetectCarplay.stopCarPlayMonitoring();
connected.remove();
disconnected.remove();

The default export remains available for backwards compatibility. See Monitoring for lifecycle, diagnostics, and cleanup. Basic iOS audio-route monitoring needs no permission; call requestPermissionsAsync on iOS only after configuring the location usage descriptions through ios.backgroundLocation.

React hook

import { useCarPlay } from 'expo-detect-carplay';

function VehicleStatus() {
  const { connected, transport, isMonitoring } = useCarPlay({
    autoStart: true,
  });

  return null; // Render these values in your application UI.
}

Typed config-plugin options

import type { CarPlayPluginProps } from 'expo-detect-carplay/plugin';

See Config plugin for Android Auto registration, iOS background location, the Driving Task entitlement, and integration options.

Documentation

• Documentation index
• Getting started
• Monitoring
• Platform support
• Config plugin
• Background geolocation
• Event logging and forwarding
• Errors
• Generated runtime API
• Generated config-plugin API
• llms.txt

Contributing

npm run test:all

For clean-prebuild, emulator/device, and physical-accessory coverage, follow the repository end-to-end test environment.

Repository-specific guidance is in AGENTS.md.

License

MIT