File: development-and-debugging.md | Updated: 11/15/2025
Hide navigation
Search
Ctrl K
Home Guides EAS Reference Learn
Archive Expo Snack Discord and Forums Newsletter
Copy page
Learn about development best practices and debugging techniques for Expo config plugins.
Copy page
Developing a plugin is a great way to extend the Expo ecosystem. However, there are times you'll want to debug your plugin. This page provides some of the best practices for developing and debugging a plugin.
Use modifier previews to debug the results of your plugin live.
To make plugin development easier, we've added plugin support to expo-module-scripts
. Refer to the config plugins guide
for more info on using TypeScript, and Jest to build plugins.
Use the following dependencies in a library that provides a config plugin:
package.json
Copy
{ "dependencies": {}, "devDependencies": { "expo": "^54.0.0" }, "peerDependencies": { "expo": ">=54.0.0" }, "peerDependenciesMeta": { "expo": { "optional": true } } }
expo to build against a specific version.expo-module-scripts
as a development dependency, but it's not required.The expo/config-plugins and expo/config packages are re-exported from the expo package.
const { ... } = require('expo/config-plugins'); const { ... } = require('expo/config');
Importing through the expo package ensures that you are using the version of the expo/config-plugins and expo/config packages that are depended on by the expo package.
If you do not import the package through the expo re-export in this way, you may accidentally be importing an incompatible version (depending on the implementation details of module hoisting in the package manager used by the developer consuming the module) or be unable to import the module at all (if using "plug and play" features of a package manager such as Yarn Berry or pnpm).
Config types are exported directly from expo/config, so there is no need to install or import from expo/config-types:
import { ExpoConfig, ConfigContext } from 'expo/config';
gradle.properties. If you want to modify some code in the Podfile, consider writing to JSON and having the Podfile read the static values.withXcodeProject to minimize the amount of times a file is read and parsed.Plugin structure and scaffolding
By default, npx expo prebuild runs transformations on a source template
associated with the Expo SDK version that a project is using. The SDK version is defined in the app.json or inferred from the installed version of expo that the project has.
When Expo SDK upgrades to a new version of React Native for instance, the template may change significantly to account for changes in React Native or new releases of Android or iOS.
If your plugin is mostly using static modifications then it will usually work well across SDK versions. If it's using a regular expression to transform application code, then you'll definitely want to document which Expo SDK version your plugin is intended for. During the SDK release cycle, there is a beta period where you can test if your plugin works with the new version before it's released.
Properties are used to customize the way a plugin works during prebuild. They must always be static values (no functions, or promises). Consider the following types:
type StaticValue = boolean | number | string | null | StaticArray | StaticObject; type StaticArray = StaticValue[]; interface StaticObject { [key: string]: StaticValue | undefined; }
Static properties are required because the app config must be serializable to JSON for use as the app manifest.
If possible, attempt to make your plugin work without props, this will help resolution tooling like expo install
or VS Code Expo Tools
work better. Remember that every property you add increases complexity, making it harder to change in the future and increases the amount of features you'll need to test. Good default values are preferred over mandatory configuration when feasible.
We highly recommend installing the Expo Tools VS Code extension as this will perform automatic validation on the plugins and surface error information along with other quality of life improvements for Config Plugin development.
You can develop plugins easily using JS, but if you want to set up Jest tests and use TypeScript, you will want a monorepo.
A monorepo will enable you to work on a node module and import it in your app config like you would if it were published to npm. Expo config plugins have full monorepo support built-in so all you need to do is set up a project.
In your monorepo's packages/ directory, create a module, and bootstrap a config plugin
in it.
If you aren't comfortable setting up a monorepo, you can try manually running a plugin:
npm pack in the package with the config pluginnpm install path/to/react-native-my-package-1.0.0.tgz, this will add the package to your package.json dependencies object.plugins array in your app.json: { "plugins": ["react-native-my-package"] }
version in the package's package.json and repeat the process.Modifying native files with plugins
Packages should attempt to use the built-in AndroidManifest.xml merging system before using a config plugin. This can be used for static, non-optional features like permissions. This will ensure features are merged during build-time and not prebuild-time, which minimizes the possibility of the configuration being missed due to users forgetting to prebuild. The drawback is that users cannot use introspection to preview the changes and debug any potential issues.
Here is an example of a package's AndroidManifest.xml, which injects a required permission:
AndroidManifest.xml
Copy
<manifest package="expo.modules.filesystem" xmlns:android="http://schemas.android.com/apk/res/android"> <uses-permission android:name="android.permission.INTERNET"/> </manifest>
If you're building a plugin for your local project, or if your package needs more control, then you should implement a plugin.
You can use built-in types and helpers to ease the process of working with complex objects. Here's an example of adding a <meta-data android:name="..." android:value="..."/> to the default <application android:name=".MainApplication" />.
my-config-plugin.ts
Copy
import { AndroidConfig, ConfigPlugin, withAndroidManifest } from 'expo/config-plugins'; import { ExpoConfig } from 'expo/config'; // Using helpers keeps error messages unified and helps cut down on XML format changes. const { addMetaDataItemToMainApplication, getMainApplicationOrThrow } = AndroidConfig.Manifest; export const withMyCustomConfig: ConfigPlugin = config => { return withAndroidManifest(config, async config => { // Modifiers can be async, but try to keep them fast. config.modResults = await setCustomConfigAsync(config, config.modResults); return config; }); }; // Splitting this function out of the mod makes it easier to test. async function setCustomConfigAsync( config: Pick<ExpoConfig, 'android'>, androidManifest: AndroidConfig.Manifest.AndroidManifest ): Promise<AndroidConfig.Manifest.AndroidManifest> { const appId = 'my-app-id'; // Get the <application /> tag and assert if it doesn't exist. const mainApplication = getMainApplicationOrThrow(androidManifest); addMetaDataItemToMainApplication( mainApplication, // value for `android:name` 'my-app-id-key', // value for `android:value` appId ); return androidManifest; }
Show More
Using the withInfoPlist is a bit safer than statically modifying the expo.ios.infoPlist object in the app.json because it reads the contents of the Info.plist and merges it with the expo.ios.infoPlist, this means you can attempt to keep your changes from being overwritten.
Here's an example of adding a GADApplicationIdentifier to the Info.plist:
my-config-plugin.ts
Copy
import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins'; // Pass `<string>` to specify that this plugin requires a string property. export const withCustomConfig: ConfigPlugin<string> = (config, id) => { return withInfoPlist(config, config => { config.modResults.GADApplicationIdentifier = id; return config; }); };
The iOS Podfile is the config file for CocoaPods, the dependency manager on iOS. It is similar to package.json for iOS. The Podfile is a Ruby file, which means you cannot safely modify it from Expo config plugins and should opt for another approach, such as Expo Autolinking hooks.
We do expose one mechanism for safely interacting with the Podfile, but it's very limited. The versioned template Podfile
is hard coded to read from a static JSON file Podfile.properties.json, we expose a mod (ios.podfileProperties, withPodfileProperties) to safely read and write from this file. This is used by expo-build-properties
and to configure the JavaScript engine.
pluginHistory_internal.pluginHistory was created to prevent duplicate plugins from running while migrating from legacy UNVERSIONED plugins to versioned plugins.
my-config-plugin.ts
Copy
import { ConfigPlugin, createRunOncePlugin } from 'expo/config-plugins'; // Keeping the name, and version in sync with it's package. const pkg = require('my-cool-plugin/package.json'); const withMyCoolPlugin: ConfigPlugin = config => config; // A helper method that wraps `withRunOnce` and appends items to `pluginHistory`. export default createRunOncePlugin( // The plugin to guard. withMyCoolPlugin, // An identifier used to track if the plugin has already been run. pkg.name, // Optional version property, if omitted, defaults to UNVERSIONED. pkg.version );
You may find that your project requires configuration to be setup before the JS engine has started. For example, in expo-splash-screen on Android, we need to specify the resize mode in the MainActivity.java's onCreate method. Instead of attempting to dangerously regex these changes into the MainActivity via a dangerous mod, we use a system of lifecycle hooks and static settings to safely ensure the feature works across all supported Android languages (Java, Kotlin), versions of Expo, and combination of config plugins.
This system is made up of three components:
ReactActivityLifecycleListeners: An interface exposed by expo-modules-core to get a native callback when the project ReactActivity's onCreate method is invoked.withStringsXml: A mod exposed by expo/config-plugins which writes a property to the Android strings.xml file, the library can safely read the strings.xml value and do initial setup. The string XML values follow a designated format for consistency.SingletonModule (optional): An interface exposed by expo-modules-core to create a shared interface between native modules and ReactActivityLifecycleListeners.Consider this example: We want to set a custom "value" string to a property on the Android Activity, directly after the onCreate method was invoked. We can do this safely by creating a node module expo-custom, implementing expo-modules-core, and Expo config plugins:
First, we register the ReactActivity listener in our Android native module, this will only be invoked if the user has expo-modules-core support, setup in their project (default in projects bootstrapped with Expo CLI, Create React Native App, Ignite CLI, and Expo prebuilding).
expo-custom/android/src/main/java/expo/modules/custom/CustomPackage.kt
Copy
package expo.modules.custom import android.content.Context import expo.modules.core.BasePackage import expo.modules.core.interfaces.ReactActivityLifecycleListener class CustomPackage : BasePackage() { override fun createReactActivityLifecycleListeners(activityContext: Context): List<ReactActivityLifecycleListener> { return listOf(CustomReactActivityLifecycleListener(activityContext)) } // ... }
Next we implement the ReactActivity listener, this is passed the Context and is capable of reading from the project strings.xml file.
expo-custom/android/src/main/java/expo/modules/custom/CustomReactActivityLifecycleListener.kt
Copy
package expo.modules.custom import android.app.Activity import android.content.Context import android.os.Bundle import android.util.Log import expo.modules.core.interfaces.ReactActivityLifecycleListener class CustomReactActivityLifecycleListener(activityContext: Context) : ReactActivityLifecycleListener { override fun onCreate(activity: Activity, savedInstanceState: Bundle?) { // Execute static tasks before the JS engine starts. // These values are defined via config plugins. var value = getValue(activity) if (value != "") { // Do something to the Activity that requires the static value... } } // Naming is node module name (`expo-custom`) plus value name (`value`) using underscores as a delimiter // i.e. `expo_custom_value` // `@expo/vector-icons` + `iconName` -> `expo__vector_icons_icon_name` private fun getValue(context: Context): String = context.getString(R.string.expo_custom_value).toLowerCase() }
Show More
We must define default string.xml values which the user will overwrite locally by using the same name property in their strings.xml file.
expo-custom/android/src/main/res/values/strings.xml
Copy
<?xml version="1.0" encoding="utf-8"?> <resources> <string name="expo_custom_value" translatable="false"></string> </resources>
At this point, bare users can configure this value by creating a string in their local strings.xml file (assuming they also have expo-modules-core support setup):
./android/app/src/main/res/values/strings.xml
Copy
<?xml version="1.0" encoding="utf-8"?> <resources> <string name="expo_custom_value" translatable="false">I Love Expo</string> </resources>
For managed users, we can expose this functionality (safely!) via an Expo config plugin:
expo-custom/app.plugin.js
Copy
const { AndroidConfig, withStringsXml } = require('expo/config-plugins'); function withCustom(config, value) { return withStringsXml(config, config => { config.modResults = setStrings(config.modResults, value); return config; }); } function setStrings(strings, value) { // Helper to add string.xml JSON items or overwrite existing items with the same name. return AndroidConfig.Strings.setStringItem( [ // XML represented as JSON // <string name="expo_custom_value" translatable="false">value</string> { $: { name: 'expo_custom_value', translatable: 'false' }, _: value }, ], strings ); }
Show More
Managed Expo users can now interact with this API like so:
app.json
Copy
{ "expo": { "plugins": [["expo-custom", "I Love Expo"]] } }
By re-running npx expo prebuild -p (eas build -p android, or npx expo run:ios) the user can now see the changes, safely applied in their managed project!
As you can see from the example, we rely heavily on application code (expo-modules-core) to interact with application code (the native project). This ensures that our config plugins are safe and reliable, hopefully for a very long time!
You can debug config plugins by running EXPO_DEBUG=1 expo prebuild. If EXPO_DEBUG is enabled, the plugin stack logs will be printed, these are useful for viewing which mods ran, and in what order they ran in. To view all static plugin resolution errors, enable EXPO_CONFIG_PLUGIN_VERBOSE_ERRORS, this should only be needed for plugin authors. By default, some automatic plugin errors are hidden because they're usually related to versioning issues and aren't very helpful (that is, legacy package doesn't have a config plugin yet).
Running npx expo prebuild --clean will remove the generated native directories before compiling.
You can also run npx expo config --type prebuild to print the results of the plugins with the mods unevaluated (no code is generated).
Expo CLI commands can be profiled using EXPO_PROFILE=1.
Introspection is an advanced technique used to read the evaluated results of modifiers without generating any code in the project. This can be used to quickly debug the results of static modifications
without needing to run prebuild. You can interact with introspection live, by using the preview feature
of vscode-expo.
You can try introspection by running expo config --type introspect in a project.
Introspection only supports a subset of modifiers:
android.manifestandroid.gradlePropertiesandroid.stringsandroid.colorsandroid.colorsNightandroid.stylesios.infoPlistios.entitlementsios.expoPlistios.podfilePropertiesIntrospection only works on safe modifiers (static files like JSON, XML, plist, properties), except
ios.xcodeprojwhich often requires file system changes, making it non idempotent.
Introspection works by creating custom base mods that work like the default base mods, except they don't write the modResults to disk at the end. Instead of persisting, they save the results to the app config under _internal.modResults, followed by the name of the mod such as the ios.infoPlist mod saves to _internal.modResults.ios.infoPlist: {}.
As a real-world example, introspection is used by eas-cli to determine what the final iOS entitlements will be in a managed app, so it can sync them with the Apple Developer Portal before building. Introspection can also be used as a handy debugging and development tool.
To make eas build work the same as the classic expo build service, we added support for "legacy plugins" which are applied automatically to a project when they're installed in the project.
For instance, say a project has expo-camera installed but doesn't have plugins: ['expo-camera'] in their app.json. Expo CLI would automatically add expo-camera to the plugins to ensure that the required camera and microphone permissions are added to the project. The user can still customize the expo-camera plugin by adding it to the plugins array manually, and the manually defined plugins will take precedence over the automatic plugins.
You can debug which plugins were added by running expo config --type prebuild and seeing the _internal.pluginHistory property.
This will show an object with all plugins that were added using withRunOnce plugin from expo/config-plugins.
Notice that expo-location uses version: '11.0.0', and react-native-maps uses version: 'UNVERSIONED'. This means the following:
expo-location and react-native-maps are both installed in the project.expo-location is using the plugin from the project's node_modules/expo-location/app.plugin.jsreact-native-maps installed in the project doesn't have a plugin, so it's falling back on the unversioned plugin that is shipped with expo-cli for legacy support.{ _internal: { pluginHistory: { 'expo-location': { name: 'expo-location', version: '11.0.0', }, 'react-native-maps': { name: 'react-native-maps', version: 'UNVERSIONED', }, }, }, };
For the most stable experience, you should try to have no UNVERSIONED plugins in your project. This is because the UNVERSIONED plugin may not support the native code in your project. For instance, say you have an UNVERSIONED Facebook plugin in your project, if the Facebook native code or plugin has a breaking change, that will break the way your project prebuilds and cause it to error on build.
Plugins can transform application code with regular expressions, but these modifications are dangerous if the template changes over time then the regex becomes hard to predict (similarly if the user modifies a file manually or uses a custom template). Here are some examples of files you shouldn't modify manually, and alternatives.
Gradle files are written in either Groovy or Kotlin. They are used to manage dependencies, versioning, and other settings in the Android app. Instead of modifying them directly with the withProjectBuildGradle, withAppBuildGradle, or withSettingsGradle mods, utilize the static gradle.properties file.
The gradle.properties is a static key/value pair that groovy files can read from. For example, say you wanted to control some toggle in Groovy:
gradle.properties
Copy
expo.react.jsEngine=hermes
Then later in a Gradle file:
app/build.gradle
Copy
project.ext.react = [enableHermes: findProperty('expo.react.jsEngine') ?: 'jsc']
gradle.properties, use camel case separated by .s, and usually starting with the expo prefix to denote that the property is managed by prebuild.property: Get a property, throw an error if the property is not defined.findProperty: Get a property without throwing an error if the property is missing. This can often be used with the ?: operator to provide a default value.Generally, you should only interact with the Gradle file via Expo Autolinking , this provides a programmatic interface with the project files.
Some modules may need to add delegate methods to the project AppDelegate. This can be done safely by using AppDelegate subscribers
or dangerously via the withAppDelegate mod (strongly discouraged). Using AppDelegate subscribers allows native Expo modules to react to important events in a safe and reliable way.
Below are some examples of the AppDelegate subscribers in action. Additionally, you will find many examples in community repositories on GitHub (one such example ).
expo-linking: LinkingAppDelegateSubscriber.swift
(openURL)expo-notifications: NotificationsAppDelegateSubscriber.swift
(didRegisterForRemoteNotificationsWithDeviceToken, didFailToRegisterForRemoteNotificationsWithError, didReceiveRemoteNotification)The Podfile can be customized with a regular expression (this is considered dangerous because these types of changes do not compose well and multiple changes are likely to collide), but it's more reliable to instead set configuration values in JSON file called Podfile.properties.json. See how podfile_properties is used to customize the Podfile below:
Podfile
Copy
require 'json' podfile_properties = JSON.parse(File.read(File.join(__dir__, 'Podfile.properties.json'))) rescue {} platform :ios, podfile_properties['ios.deploymentTarget'] || '15.1' target 'yolo27' do use_expo_modules! # ... # podfile_properties['your_property'] end
Generally, you should only interact with the Podfile via Expo Autolinking , this provides a programmatic interface with the project files.
The Expo CLI npx expo prebuild command uses @expo/prebuild-config
to get the default base modifiers. These defaults only manage a subset of common files, if you want to manage custom files you can do that locally by adding new base modifiers.
For example, say you wanted to add support for managing the ios/*/AppDelegate.h file, you could do this by adding a ios.appDelegateHeader modifier.
This example uses
tsxfor simple local TypeScript support, this isn't strictly necessary. Learn more .
withAppDelegateHeaderBaseMod.ts
Copy
import { ConfigPlugin, IOSConfig, Mod, withMod, BaseMods } from 'expo/config-plugins'; import fs from 'fs'; /** * A plugin which adds new base modifiers to the prebuild config. */ export function withAppDelegateHeaderBaseMod(config) { return BaseMods.withGeneratedBaseMods<'appDelegateHeader'>(config, { platform: 'ios', providers: { // Append a custom rule to supply AppDelegate header data to mods on `mods.ios.appDelegateHeader` appDelegateHeader: BaseMods.provider<IOSConfig.Paths.AppDelegateProjectFile>({ // Get the local filepath that should be passed to the `read` method. getFilePath({ modRequest: { projectRoot } }) { const filePath = IOSConfig.Paths.getAppDelegateFilePath(projectRoot); // Replace the .m with a .h if (filePath.endsWith('.m')) { return filePath.substr(0, filePath.lastIndexOf('.')) + '.h'; } // Possibly a Swift project... throw new Error(`Could not locate a valid AppDelegate.h at root: "${projectRoot}"`); }, // Read the input file from the filesystem. async read(filePath) { return IOSConfig.Paths.getFileInfo(filePath); }, // Write the resulting output to the filesystem. async write(filePath: string, { modResults: { contents } }) { await fs.promises.writeFile(filePath, contents); }, }), }, }); } /** * (Utility) Provides the AppDelegate header file for modification. */ export const withAppDelegateHeader: ConfigPlugin<Mod<IOSConfig.Paths.AppDelegateProjectFile>> = ( config, action ) => { return withMod(config, { platform: 'ios', mod: 'appDelegateHeader', action, }); }; // (Example) Log the contents of the modifier. export const withSimpleAppDelegateHeaderMod = config => { return withAppDelegateHeader(config, config => { console.log('modify header:', config.modResults); return config; }); };
Show More
To use this new base mod, add it to the plugins array. The base mod MUST be added last after all other plugins that use the mod, this is because it must write the results to disk at the end of the process.
app.config.js
Copy
// Required for external files using TS require('tsx/cjs'); import { withAppDelegateHeaderBaseMod, withSimpleAppDelegateHeaderMod, } from './withAppDelegateHeaderBaseMod.ts'; export default ({ config }) => { if (!config.plugins) config.plugins = []; config.plugins.push( withSimpleAppDelegateHeaderMod, // Base mods MUST be last withAppDelegateHeaderBaseMod ); return config; };
Show More
For more info, see the PR that adds support for this feature.
When a node module is installed with the npx expo install command, if it includes a config plugin, it will be added to the project's app config automatically. This makes setup easier and helps prevent users from forgetting to add a plugin. However, this does come with a couple of caveats:
npx expo install only adds config plugins using the root app.config.js file automatically to the app manifest. This rule was added to prevent popular packages like lodash from being mistaken for a config plugin and breaking the prebuild.expo install will only add the plugin, and not attempt to add any extra props. For example, expo-camera has optional extra props, so plugins: ['expo-camera'] is valid, but if it had mandatory props, then expo-camera would throw an error.expo install expo-camera in a project with an app.config.js, they'll see a warning like:Cannot automatically write to dynamic config at: app.config.js Please add the following to your app config { "plugins": [ "expo-camera" ] }