React Native Launch Arguments

4.1.1 · active · verified Sun Apr 19

The `react-native-launch-arguments` module provides a straightforward API for React Native applications to retrieve arguments passed during their launch. This capability is crucial for scenarios involving end-to-end testing, debugging, and advanced application configuration, allowing external tools like Detox, Appium, Maestro, or native debuggers (Xcode, `xcrun simctl`) to inject parameters directly into the running React Native app. Currently at version 4.1.1, the library typically updates as needed to maintain compatibility with new React Native releases and address platform-specific nuances. Its primary differentiation lies in offering a unified JavaScript interface to access platform-specific argument mechanisms on both iOS and Android, simplifying parameter passing that would otherwise require native bridge development. This facilitates robust testing and development workflows by externalizing configuration. It also ships with TypeScript types, enhancing developer experience for type-safe argument access.

Common errors

```
Launch arguments are unexpectedly empty when using Expo.
```
cause Known Expo bug (#31830) regarding empty passed arguments or specific argument formatting.

fix Check Expo issue #31830 for latest status and workarounds. Ensure arguments are not empty or try passing a dummy argument to initialize.
```
Launch arguments passed via `xcrun simctl launch` or Xcode Schemes are not received on iOS.
```
cause Incorrect formatting of arguments for iOS. Each argument must start with a hyphen.

fix For `xcrun simctl`, use `xcrun simctl launch booted com.MyAppBundleId -argName "argValue"`. In Xcode, ensure each argument in 'Arguments Passed On Launch' starts with a hyphen.
```
App experiences a brief delay on Android startup before `LaunchArguments` are available or the app becomes interactive.
```
cause The module waits for the Android Activity to reach the `RESUMED` state due to a React Native core issue (#37518), which can introduce a small startup delay.

fix This is an internal workaround. Monitor React Native issue #37518 for a native fix that would allow this dependency to be removed.

Warnings

gotcha On Android, the module may introduce minor delays in app loading time. This is because it force-waits for the Android activity to reach the `RESUMED` state, a workaround related to an outstanding React Native issue (#37518) regarding native module initialization.
Fix: There is no direct fix within `react-native-launch-arguments`. Monitor React Native issue #37518 for resolution, which will remove this necessity.
gotcha There is a known bug in Expo (issue #31830) where passing empty arguments to `react-native-launch-arguments` can result in unexpected behavior or failure to receive arguments correctly.
Fix: Refer to Expo issue #31830 for updates and potential workarounds. As a temporary measure, ensure non-empty arguments are always passed when using Expo.
gotcha When passing launch arguments on iOS, particularly via Xcode Schemes or `xcrun simctl`, each argument requires a preceding hyphen (e.g., `-hello "world"`). Incorrect formatting will prevent arguments from being received by the module.
Fix: Always prepend each argument with a hyphen. Consult the 'Platform-specific Notes' section in the documentation for detailed examples on Xcode and `xcrun simctl` usage.

Install

npm install react-native-launch-arguments npm
yarn add react-native-launch-arguments yarn
pnpm add react-native-launch-arguments pnpm

Imports

LaunchArguments
wrong:
```
const { LaunchArguments } = require('react-native-launch-arguments');
```
correct:
```
import { LaunchArguments } from 'react-native-launch-arguments';
```
The library primarily uses ES Module syntax. While CJS require might work in some setups, ESM imports are recommended and fully supported, especially for TypeScript users.
LaunchArguments.value()
```
const args = LaunchArguments.value();
```
Used to synchronously retrieve the parsed launch arguments. Returns an object of key-value pairs.
LaunchArguments.value<T>() (TypeScript)
```
interface MyArgs { userId?: string; debugMode?: boolean; }; const args = LaunchArguments.value<MyArgs>();
```
Allows passing a type argument for type-safe access to launch arguments within TypeScript projects, leveraging the shipped type definitions.

Quickstart

Demonstrates how to import and retrieve launch arguments with TypeScript, including defining expected argument types and conditional logic based on received values for common use cases like authentication and environment configuration.

import { LaunchArguments } from 'react-native-launch-arguments';

interface MyExpectedArgs {
  authToken?: string;
  skipAuth?: boolean;
  environment?: 'dev' | 'staging' | 'prod';
}

// Retrieve launch arguments with type safety
const args = LaunchArguments.value<MyExpectedArgs>();

console.log('Application launched with arguments:', args);

// Example of conditional logic based on launch arguments
if (args.skipAuth) {
  console.log('Authentication flow skipped as per launch arguments.');
} else {
  console.log('Authentication is required.');
}

// Simulate an API call that might use an auth token from launch args
const performAuthenticatedAction = async (token?: string) => {
  if (token) {
    console.log(`Using auth token (first 5 chars): ${token.substring(0, 5)}...`);
    // In a real app, this would be a network request with the token
    await new Promise(resolve => setTimeout(resolve, 1000));
    console.log('Authenticated action completed.');
  } else {
    console.warn('No authentication token provided via launch arguments.');
  }
};

performAuthenticatedAction(args.authToken);

if (args.environment) {
  console.log(`Running in ${args.environment} environment.`);
}

view raw JSON →