{"id":11778,"library":"react-native-launch-arguments","title":"React Native Launch Arguments","description":"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.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/iamolegga/react-native-launch-arguments","tags":["javascript","react","native","react-native","launch","arguments","typescript"],"install":[{"cmd":"npm install react-native-launch-arguments","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-launch-arguments","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-launch-arguments","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native projects.","package":"react","optional":false},{"reason":"Core peer dependency for any React Native module.","package":"react-native","optional":false}],"imports":[{"note":"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.","wrong":"const { LaunchArguments } = require('react-native-launch-arguments');","symbol":"LaunchArguments","correct":"import { LaunchArguments } from 'react-native-launch-arguments';"},{"note":"Used to synchronously retrieve the parsed launch arguments. Returns an object of key-value pairs.","symbol":"LaunchArguments.value()","correct":"const args = LaunchArguments.value();"},{"note":"Allows passing a type argument for type-safe access to launch arguments within TypeScript projects, leveraging the shipped type definitions.","symbol":"LaunchArguments.value<T>() (TypeScript)","correct":"interface MyArgs { userId?: string; debugMode?: boolean; }; const args = LaunchArguments.value<MyArgs>();"}],"quickstart":{"code":"import { LaunchArguments } from 'react-native-launch-arguments';\n\ninterface MyExpectedArgs {\n  authToken?: string;\n  skipAuth?: boolean;\n  environment?: 'dev' | 'staging' | 'prod';\n}\n\n// Retrieve launch arguments with type safety\nconst args = LaunchArguments.value<MyExpectedArgs>();\n\nconsole.log('Application launched with arguments:', args);\n\n// Example of conditional logic based on launch arguments\nif (args.skipAuth) {\n  console.log('Authentication flow skipped as per launch arguments.');\n} else {\n  console.log('Authentication is required.');\n}\n\n// Simulate an API call that might use an auth token from launch args\nconst performAuthenticatedAction = async (token?: string) => {\n  if (token) {\n    console.log(`Using auth token (first 5 chars): ${token.substring(0, 5)}...`);\n    // In a real app, this would be a network request with the token\n    await new Promise(resolve => setTimeout(resolve, 1000));\n    console.log('Authenticated action completed.');\n  } else {\n    console.warn('No authentication token provided via launch arguments.');\n  }\n};\n\nperformAuthenticatedAction(args.authToken);\n\nif (args.environment) {\n  console.log(`Running in ${args.environment} environment.`);\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"There is no direct fix within `react-native-launch-arguments`. Monitor React Native issue #37518 for resolution, which will remove this necessity.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when used with affected Expo SDK versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Check Expo issue #31830 for latest status and workarounds. Ensure arguments are not empty or try passing a dummy argument to initialize.","cause":"Known Expo bug (#31830) regarding empty passed arguments or specific argument formatting.","error":"Launch arguments are unexpectedly empty when using Expo."},{"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.","cause":"Incorrect formatting of arguments for iOS. Each argument must start with a hyphen.","error":"Launch arguments passed via `xcrun simctl launch` or Xcode Schemes are not received on iOS."},{"fix":"This is an internal workaround. Monitor React Native issue #37518 for a native fix that would allow this dependency to be removed.","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.","error":"App experiences a brief delay on Android startup before `LaunchArguments` are available or the app becomes interactive."}],"ecosystem":"npm"}