Skip to main content

Expo Setup

React Native App Auth provides seamless integration with Expo through our config plugin, supporting Expo SDK 57+ with Continuous Native Generation (CNG).

Prerequisites​

  • Expo SDK 57 or later
  • CNG workflow (not Expo Go)
  • expo prebuild capability

Quick Start​

1. Install the Library​

npm install react-native-app-auth
# or
yarn add react-native-app-auth

For iOS scene support, also install expo-build-properties:

npx expo install expo-build-properties

2. Configure the Plugin​

Add the plugins to your app.json or app.config.js. For iOS scenes, keep react-native-app-auth before expo-build-properties, as shown below. The reverse order can cause the scene transformation to fail during prebuild.

{
  "expo": {
    "plugins": [
      [
        "react-native-app-auth",
        {
          "redirectUrls": ["com.yourapp.scheme://oauth"]
        }
      ],
      [
        "expo-build-properties",
        {
          "ios": {
            "enableSceneSupport": true
          }
        }
      ]
    ]
  }
}

Configuration Options:

  • redirectUrls (required): Array of OAuth redirect URLs for your app
    • The URL scheme (before ://) will be automatically configured for both iOS and Android
    • Example: "com.myapp://oauth" → scheme is com.myapp

3. Generate Native Projects​

Run prebuild to generate iOS and Android projects with OAuth configuration:

npx expo prebuild --clean

This automatically:

  • iOS: Adds URL scheme to Info.plist and configures bridging headers
  • Android: Sets up manifest placeholders in build.gradle

The plugin also forwards Android activity results for resumePendingAuthorize(). Call that method at startup with the same token-exchange options as authorize() to recover a browser flow after Android recreates the application process.

The SDK 57 scene delegate forwards URL callbacks to the patched AppDelegate.

4. Use the Library​

import { authorize, AuthConfiguration } from 'react-native-app-auth';

const config: AuthConfiguration = {
  issuer: 'https://your-oauth-provider.com',
  clientId: 'your-client-id',
  redirectUrl: 'com.yourapp.scheme://oauth', // Must match app.json
  scopes: ['openid', 'profile', 'email'],
};

// Perform authentication
try {
  const result = await authorize(config);
  console.log('Access token:', result.accessToken);
} catch (error) {
  console.error('Auth error:', error);
}

Validation​

After running expo prebuild, verify the configuration was applied correctly:

iOS Configuration​

Check that your URL scheme was added to ios/YourApp/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.yourapp.scheme</string>
    </array>
  </dict>
</array>

Android Configuration​

Check that the manifest placeholder was added to android/app/build.gradle:

android {
  defaultConfig {
    manifestPlaceholders.appAuthRedirectScheme = 'com.yourapp.scheme'
  }
}

The plugin sets this key after existing placeholder configuration, preserving unrelated entries, map expressions, and additive assignments.

TypeScript Support​

The plugin is built with TypeScript and provides full type safety. Import types as needed:

import { 
  AuthConfiguration, 
  AuthorizeResult, 
  RefreshResult 
} from 'react-native-app-auth';

Example App​

Check out our working example in examples/expo-cng/ which demonstrates:

  • Complete TypeScript implementation
  • Expo config plugin setup
  • OAuth flow with Duende IdentityServer demo
  • Native project generation validation

Troubleshooting​

Plugin Not Found​

If you see "Package 'react-native-app-auth' does not contain a valid config plugin":

  1. Ensure you're using the latest version of the library
  2. Clear your cache: npx expo install --fix
  3. Try npx expo prebuild --clean to regenerate projects

URL Scheme Conflicts​

If you have React Navigation deep linking, ensure your OAuth scheme is different:

{
  "expo": {
    "plugins": [
      [
        "react-native-app-auth", 
        { "redirectUrls": ["com.myapp.auth://oauth"] }
      ]
    ]
  }
}

Migration from Manual Setup​

If you're migrating from manual iOS/Android setup:

  1. Remove manual URL scheme configurations from Info.plist and build.gradle
  2. Remove manual AppDelegate modifications (the plugin handles this automatically for Expo SDK 57+)
  3. Add the plugin configuration to app.json
  4. Run npx expo prebuild --clean

Limitations​

  • Expo SDK 57+ only: Earlier versions require manual setup
  • CNG workflow only: Expo Go is not supported (OAuth requires native configuration)
  • First-party providers: Some OAuth providers may require additional native configuration

For advanced use cases or non-Expo projects, see the Manual Setup Guide.