Config Plugin API Reference

This is the complete API reference for @expo/config-plugins. All exports are available from the main package:

import { 
  ConfigPlugin,
  withPlugins,
  withInfoPlist,
  withAndroidManifest,
  AndroidConfig,
  IOSConfig,
} from '@expo/config-plugins';

Core Types

ConfigPlugin

Plugin.types.ts

export type ConfigPlugin<Props = void> = (config: ExpoConfig, props: Props) => ExpoConfig;

The main plugin type. A function that receives an ExpoConfig and optional props, then returns a modified ExpoConfig. Example:

import { ConfigPlugin } from '@expo/config-plugins';

const withCustom: ConfigPlugin<{ value: string }> = (config, { value }) => {
  config.name = value;
  return config;
};

StaticPlugin

Plugin.types.ts

export type StaticPlugin<T = any> = [string | ConfigPlugin<T>, T];

A plugin with props, as used in app.json. The first element is the plugin (string or function), the second is props. Example:

app.json

{
  "plugins": [
    ["expo-camera", { "cameraPermission": "Allow app to use camera" }]
  ]
}

Mod

Plugin.types.ts

export type Mod<Props = any> = ((config: ExportedConfigWithProps<Props>) => 
  OptionalPromise<ExportedConfigWithProps<Props>>) & {
  isProvider?: boolean;
  isIntrospective?: boolean;
};

A mod is a function that modifies a specific native file. It receives the config with modResults (the file contents). Example:

const infoPlistMod: Mod<InfoPlist> = (config) => {
  config.modResults.CFBundleDisplayName = config.name;
  return config;
};

ModConfig

Plugin.types.ts

export interface ModConfig {
  android?: {
    dangerous?: Mod<unknown>;
    finalized?: Mod<unknown>;
    manifest?: Mod<AndroidManifest>;
    strings?: Mod<ResourceXML>;
    colors?: Mod<ResourceXML>;
    colorsNight?: Mod<ResourceXML>;
    styles?: Mod<ResourceXML>;
    mainActivity?: Mod<ApplicationProjectFile>;
    mainApplication?: Mod<ApplicationProjectFile>;
    appBuildGradle?: Mod<GradleProjectFile>;
    projectBuildGradle?: Mod<GradleProjectFile>;
    settingsGradle?: Mod<GradleProjectFile>;
    gradleProperties?: Mod<PropertiesItem[]>;
  };
  ios?: {
    dangerous?: Mod<unknown>;
    finalized?: Mod<unknown>;
    infoPlist?: Mod<InfoPlist>;
    entitlements?: Mod<Plist>;
    expoPlist?: Mod<Plist>;
    xcodeproj?: Mod<XcodeProject>;
    appDelegate?: Mod<AppDelegateProjectFile>;
    podfileProperties?: Mod<Record<string, string>>;
  };
}

Defines all available mods for iOS and Android platforms.

ExportedConfigWithProps

Plugin.types.ts

export interface ExportedConfigWithProps<Data = any> extends ExportedConfig {
  modResults: Data;
  modRequest: ModProps<Data>;
  readonly modRawConfig: ExpoConfig;
}

The config object passed to mod functions, including:

modResults: The parsed file contents
modRequest: Metadata about the current mod
modRawConfig: The original, unmodified config

Plugin Composition

withPlugins

withPlugins.ts

export const withPlugins: ConfigPlugin<(StaticPlugin | ConfigPlugin | string)[]>;

Apply multiple plugins to a config in sequence. Example:

import { withPlugins } from '@expo/config-plugins';

const config = withPlugins(baseConfig, [
  'expo-camera',
  'expo-location',
  [withCustom, { value: 'test' }],
]);

withRunOnce

withRunOnce.ts

export const withRunOnce: ConfigPlugin<{
  plugin: ConfigPlugin<void>;
  name: string;
  version?: string;
}>;

Ensure a plugin only runs once, even if applied multiple times. Example:

import { withRunOnce } from '@expo/config-plugins';

const config = withRunOnce(baseConfig, {
  plugin: myPlugin,
  name: 'my-plugin',
  version: '1.0.0',
});

createRunOncePlugin

withRunOnce.ts

export function createRunOncePlugin<T>(
  plugin: ConfigPlugin<T>,
  name: string,
  version?: string
): ConfigPlugin<T>;

Helper to wrap a plugin with run-once logic. Example:

import { createRunOncePlugin } from '@expo/config-plugins';

const withMyPlugin: ConfigPlugin<Props> = (config, props) => {
  // Plugin logic
  return config;
};

export default createRunOncePlugin(withMyPlugin, 'withMyPlugin', '1.0.0');

iOS Plugins

withInfoPlist

ios-plugins.ts

export const withInfoPlist: ConfigPlugin<Mod<InfoPlist>>;

Modify the iOS Info.plist file. Example:

import { withInfoPlist } from '@expo/config-plugins';

const config = withInfoPlist(baseConfig, (config) => {
  config.modResults.NSCameraUsageDescription = 'Allow camera access';
  config.modResults.UIBackgroundModes = ['remote-notification'];
  return config;
});

withEntitlementsPlist

ios-plugins.ts

export const withEntitlementsPlist: ConfigPlugin<Mod<JSONObject>>;

Modify the iOS entitlements file. Example:

import { withEntitlementsPlist } from '@expo/config-plugins';

const config = withEntitlementsPlist(baseConfig, (config) => {
  config.modResults['com.apple.developer.associated-domains'] = [
    'applinks:example.com',
  ];
  return config;
});

withXcodeProject

ios-plugins.ts

export const withXcodeProject: ConfigPlugin<Mod<XcodeProject>>;

Modify the Xcode project (.xcodeproj). Example:

import { withXcodeProject } from '@expo/config-plugins';

const config = withXcodeProject(baseConfig, (config) => {
  const xcodeProject = config.modResults;
  
  // Add build phase, framework, etc.
  xcodeProject.addBuildPhase(
    [],
    'PBXShellScriptBuildPhase',
    'Run Script',
    null,
    { shellScript: 'echo "Hello"' }
  );
  
  return config;
});

withAppDelegate

ios-plugins.ts

export const withAppDelegate: ConfigPlugin<Mod<AppDelegateProjectFile>>;

Modify the iOS AppDelegate.m file (dangerous - string manipulation). Example:

import { withAppDelegate } from '@expo/config-plugins';

const config = withAppDelegate(baseConfig, (config) => {
  if (config.modResults.language === 'objc') {
    config.modResults.contents = config.modResults.contents.replace(
      /(#import "AppDelegate.h")/,
      `$1\n#import "MyCustomHeader.h"`
    );
  }
  return config;
});

withPodfile

ios-plugins.ts

export const withPodfile: ConfigPlugin<Mod<PodfileProjectFile>>;

Modify the Podfile.

withPodfileProperties

ios-plugins.ts

export const withPodfileProperties: ConfigPlugin<Mod<Record<string, string>>>;

Modify the Podfile.properties.json (key-value pairs). Example:

import { withPodfileProperties } from '@expo/config-plugins';

const config = withPodfileProperties(baseConfig, (config) => {
  config.modResults['ios.deploymentTarget'] = '13.0';
  return config;
});

withExpoPlist

ios-plugins.ts

export const withExpoPlist: ConfigPlugin<Mod<ExpoPlist>>;

Modify the Expo.plist (Expo Updates configuration).

createInfoPlistPlugin

ios-plugins.ts

export function createInfoPlistPlugin(
  action: (expo: ExpoConfig, infoPlist: InfoPlist) => Promise<InfoPlist> | InfoPlist,
  name?: string
): ConfigPlugin;

Helper to create Info.plist plugins. Example:

import { createInfoPlistPlugin } from '@expo/config-plugins';

const withCustomKey = createInfoPlistPlugin(
  (config, infoPlist) => {
    infoPlist.MyCustomKey = config.myValue;
    return infoPlist;
  },
  'withCustomKey'
);

createEntitlementsPlugin

ios-plugins.ts

export function createEntitlementsPlugin(
  action: (expo: ExpoConfig, entitlements: JSONObject) => JSONObject,
  name: string
): ConfigPlugin;

Helper to create entitlements plugins. Example:

Entitlements.ts

import { createEntitlementsPlugin } from '@expo/config-plugins';

const withAssociatedDomains = createEntitlementsPlugin(
  (config, entitlements) => {
    if (config.ios?.associatedDomains) {
      return {
        ...entitlements,
        'com.apple.developer.associated-domains': config.ios.associatedDomains,
      };
    }
    return entitlements;
  },
  'withAssociatedDomains'
);

Android Plugins

withAndroidManifest

android-plugins.ts

export const withAndroidManifest: ConfigPlugin<Mod<AndroidManifest>>;

Modify the AndroidManifest.xml. Example:

import { withAndroidManifest } from '@expo/config-plugins';

const config = withAndroidManifest(baseConfig, (config) => {
  const manifest = config.modResults.manifest;
  
  // Add permission
  if (!manifest['uses-permission']) {
    manifest['uses-permission'] = [];
  }
  manifest['uses-permission'].push({
    $: { 'android:name': 'android.permission.CAMERA' },
  });
  
  return config;
});

withStringsXml

android-plugins.ts

export const withStringsXml: ConfigPlugin<Mod<ResourceXML>>;

Modify android/app/src/main/res/values/strings.xml. Example:

import { withStringsXml } from '@expo/config-plugins';

const config = withStringsXml(baseConfig, (config) => {
  config.modResults.resources.string.push({
    $: { name: 'custom_string' },
    _: 'My custom value',
  });
  return config;
});

withAndroidColors

android-plugins.ts

export const withAndroidColors: ConfigPlugin<Mod<ResourceXML>>;

Modify android/app/src/main/res/values/colors.xml.

withAndroidColorsNight

android-plugins.ts

export const withAndroidColorsNight: ConfigPlugin<Mod<ResourceXML>>;

Modify android/app/src/main/res/values-night/colors.xml.

withAndroidStyles

android-plugins.ts

export const withAndroidStyles: ConfigPlugin<Mod<ResourceXML>>;

Modify android/app/src/main/res/values/styles.xml.

withMainActivity

android-plugins.ts

export const withMainActivity: ConfigPlugin<Mod<ApplicationProjectFile>>;

Modify the MainActivity.java file (dangerous - string manipulation).

withMainApplication

android-plugins.ts

export const withMainApplication: ConfigPlugin<Mod<ApplicationProjectFile>>;

Modify the MainApplication.java file (dangerous - string manipulation).

withAppBuildGradle

android-plugins.ts

export const withAppBuildGradle: ConfigPlugin<Mod<GradleProjectFile>>;

Modify android/app/build.gradle. Example:

import { withAppBuildGradle } from '@expo/config-plugins';

const config = withAppBuildGradle(baseConfig, (config) => {
  if (config.modResults.language === 'groovy') {
    config.modResults.contents = config.modResults.contents.replace(
      /defaultConfig {/,
      `defaultConfig {\n        manifestPlaceholders = [customKey: "value"]`
    );
  }
  return config;
});

withProjectBuildGradle

android-plugins.ts

export const withProjectBuildGradle: ConfigPlugin<Mod<GradleProjectFile>>;

Modify android/build.gradle.

withSettingsGradle

android-plugins.ts

export const withSettingsGradle: ConfigPlugin<Mod<GradleProjectFile>>;

Modify android/settings.gradle.

withGradleProperties

android-plugins.ts

export const withGradleProperties: ConfigPlugin<Mod<PropertiesItem[]>>;

Modify android/gradle.properties as key-value pairs. Example:

import { withGradleProperties } from '@expo/config-plugins';

const config = withGradleProperties(baseConfig, (config) => {
  config.modResults.push({
    type: 'property',
    key: 'android.useAndroidX',
    value: 'true',
  });
  return config;
});

createAndroidManifestPlugin

android-plugins.ts

export function createAndroidManifestPlugin(
  action: (config: ExportedConfigWithProps, manifest: AndroidManifest) => OptionalPromise<AndroidManifest>,
  name: string
): ConfigPlugin;

Helper to create Android manifest plugins.

createStringsXmlPlugin

android-plugins.ts

export function createStringsXmlPlugin(
  action: (config: ExportedConfigWithProps, strings: ResourceXML) => OptionalPromise<ResourceXML>,
  name: string
): ConfigPlugin;

Helper to create strings.xml plugins.

Advanced Mods

withMod

withMod.ts

export function withMod<T>(
  config: ExportedConfig,
  {
    platform,
    mod,
    action,
  }: {
    platform: ModPlatform;
    mod: string;
    action: Mod<T>;
  }
): ExportedConfig;

Low-level function to add a mod to a specific platform and mod name. Example:

import { withMod } from '@expo/config-plugins';

const config = withMod(baseConfig, {
  platform: 'ios',
  mod: 'infoPlist',
  action: (config) => {
    config.modResults.MyKey = 'MyValue';
    return config;
  },
});

withDangerousMod

withDangerousMod.ts

export const withDangerousMod: ConfigPlugin<[ModPlatform, Mod<unknown>]>;

Run code before any files are read. Useful for filesystem operations. Example:

import { withDangerousMod } from '@expo/config-plugins';
import fs from 'fs';
import path from 'path';

const config = withDangerousMod(baseConfig, ['ios', async (config) => {
  const filePath = path.join(
    config.modRequest.platformProjectRoot,
    'custom-file.txt'
  );
  await fs.promises.writeFile(filePath, 'content');
  return config;
}]);

withBaseMod

withMod.ts

export function withBaseMod<T>(
  config: ExportedConfig,
  options: BaseModOptions & { action: Mod<T> }
): ExportedConfig;

Low-level function to create a base mod with provider capabilities.

Mod Compilation

compileModsAsync

mod-compiler.ts

export async function compileModsAsync(
  config: ExportedConfig,
  props: {
    projectRoot: string;
    platforms?: ModPlatform[];
    introspect?: boolean;
    assertMissingModProviders?: boolean;
  }
): Promise<ExportedConfig>;

Compile and execute all mods. This is called internally by Expo CLI.

evalModsAsync

mod-compiler.ts

export async function evalModsAsync(
  config: ExportedConfig,
  props: {
    projectRoot: string;
    introspect?: boolean;
    platforms?: ModPlatform[];
    assertMissingModProviders?: boolean;
  }
): Promise<ExportedConfig>;

Evaluate mods without adding base mods. Use for testing.

Helper Utilities

WarningAggregator

import { WarningAggregator } from '@expo/config-plugins';

// Add a warning
WarningAggregator.addWarningIOS(
  'myPlugin',
  'This is a warning message'
);

// Flush warnings
const warnings = WarningAggregator.flushWarningsAsync();

CodeGenerator

generateCode.ts

import { CodeGenerator } from '@expo/config-plugins';

// Merge code with generated sections
const result = CodeGenerator.mergeContents({
  src: existingFileContent,
  newSrc: codeToInsert,
  tag: 'my-plugin',
  anchor: /some regex/,
  offset: 1,
  comment: '//',
});

if (result.didMerge || result.didClear) {
  fileContent = result.contents;
}

Generates code with headers like:

// @generated begin my-plugin - expo prebuild (DO NOT MODIFY) sync-abc123
// Your generated code
// @generated end my-plugin

PluginError

errors.ts

import { PluginError } from '@expo/config-plugins';

throw new PluginError(
  'Something went wrong in the plugin',
  'CUSTOM_ERROR_CODE'
);

Platform-Specific Configs

AndroidConfig

import { AndroidConfig } from '@expo/config-plugins';

// Utilities for Android
AndroidConfig.Manifest.addPermission(manifest, 'CAMERA');
AndroidConfig.Permissions.ensurePermissions(manifest, ['CAMERA', 'LOCATION']);
AndroidConfig.Resources.setStrings(strings, { app_name: 'My App' });

IOSConfig

import { IOSConfig } from '@expo/config-plugins';

// Utilities for iOS
IOSConfig.BundleIdentifier.setBundleIdentifier(config, 'com.example.app');
IOSConfig.Entitlements.setAssociatedDomains(entitlements, ['applinks:example.com']);
IOSConfig.Version.setVersion(config, infoPlist, '1.0.0');

Next steps

Modifying native projects - Platform-specific guides
Testing plugins - Test strategies
Creating plugins - Build your own plugins

Introduction

Building Plugins

Common Patterns

​Core Types

​ConfigPlugin

​StaticPlugin

​Mod

​ModConfig

​ExportedConfigWithProps

​Plugin Composition

​withPlugins

​withRunOnce

​createRunOncePlugin

​iOS Plugins

​withInfoPlist

​withEntitlementsPlist

​withXcodeProject

​withAppDelegate

​withPodfile

​withPodfileProperties

​withExpoPlist

​createInfoPlistPlugin

​createEntitlementsPlugin

​Android Plugins

​withAndroidManifest

​withStringsXml

​withAndroidColors

​withAndroidColorsNight

​withAndroidStyles

​withMainActivity

​withMainApplication

​withAppBuildGradle

​withProjectBuildGradle

​withSettingsGradle

​withGradleProperties

​createAndroidManifestPlugin

​createStringsXmlPlugin

​Advanced Mods

​withMod

​withDangerousMod

​withBaseMod

​Mod Compilation

​compileModsAsync

​evalModsAsync

​Helper Utilities

​WarningAggregator

​CodeGenerator

​PluginError

​Platform-Specific Configs

​AndroidConfig

​IOSConfig

​Next steps

Core Types

ConfigPlugin

StaticPlugin

Mod

ModConfig

ExportedConfigWithProps

Plugin Composition

withPlugins

withRunOnce

createRunOncePlugin

iOS Plugins

withInfoPlist

withEntitlementsPlist

withXcodeProject

withAppDelegate

withPodfile

withPodfileProperties

withExpoPlist

createInfoPlistPlugin

createEntitlementsPlugin

Android Plugins

withAndroidManifest

withStringsXml

withAndroidColors

withAndroidColorsNight

withAndroidStyles

withMainActivity

withMainApplication

withAppBuildGradle

withProjectBuildGradle

withSettingsGradle

withGradleProperties

createAndroidManifestPlugin

createStringsXmlPlugin

Advanced Mods

withMod

withDangerousMod

withBaseMod

Mod Compilation

compileModsAsync

evalModsAsync

Helper Utilities

WarningAggregator

CodeGenerator

PluginError

Platform-Specific Configs

AndroidConfig

IOSConfig

Next steps