Expo Docs MCP Server

--- title: Create and use config plugins description: Learn how to create and use a config plugins in your Expo project. sidebar_title: Create a plugin searchRank: 4 --- This guide covers sections how to create a config plugin, how to pass parameters to a config plugin, and how to chain multiple config plugins together. It also covers how to use a config plugin from an Expo library. Using the diagram below, in this guide, you will learn the first two parts of the config plugin hierarchy: > **info** **Note:** The following sections use dynamic [app config](/workflow/configuration/) (**app.config.js/app.config.ts** instead of **app.json**), which is not required to use a simple config plugin. However, it is required to use dynamic app config when you want to create/use a function-based config plugin that accepts parameters. ## Creating a config plugin In the following section, let's create a local config plugin that adds an arbitrary property `HelloWorldMessage` to the **AndroidManifest.xml** for Android and **Info.plist** for iOS. This example will create and modify the following files. To follow along, create a **plugins** directory in the root of your project, and inside it, create **withAndroidPlugin.ts**, **withIosPlugins.ts**, and **withPlugin.ts** files. ### Create Android plugin In **withAndroidPlugin.ts**, add the following code: ```ts withAndroidPlugin.ts const withAndroidPlugin: ConfigPlugin = config => { // Define a custom message const message = 'Hello world, from Expo plugin!'; return withAndroidManifest(config, config => { const mainApplication = config?.modResults?.manifest?.application?.[0]; if (mainApplication) { // Ensure meta-data array exists if (!mainApplication['meta-data']) { mainApplication['meta-data'] = []; } // Add the custom message as a meta-data entry mainApplication['meta-data'].push({ $: { 'android:name': 'HelloWorldMessage', 'android:value': message, }, }); } return config; }); }; ``` The example code above adds a meta-data entry `HelloWorldMessage` to the **android/app/src/main/AndroidManifest.xml** file by importing `ConfigPlugin` and `withAndroidManifest` from the `expo/config-plugins` library. The [`withAndroidManifest`](/config-plugins/mods/#mod-plugins) mod plugin is an asynchronous function that accepts a config and a data object and modifies the value before returning an object. ### Create iOS plugin In **withIosPlugin.ts**, add the following code: ```ts withIosPlugin.ts const withIosPlugin: ConfigPlugin = config => { // Define the custom message const message = 'Hello world, from Expo plugin!'; return withInfoPlist(config, config => { // Add the custom message to the Info.plist file config.modResults.HelloWorldMessage = message; return config; }); }; ``` The example code above adds `HelloWorldMessage` as the custom key with a custom message in **ios/\<your-project-name\>/Info.plist** file by importing the `ConfigPlugin` and `withInfoPlist` from the `expo/config-plugins` library. The [`withInfoPlist`](/config-plugins/mods/#mod-plugins) mod plugin is an asynchronous function that accepts a config and a data object and modifies the value before returning an object. ### Create a combined plugin Now you can create a combined plugin that applies both platform-specific plugins. This approach allows the maintenance of platform-specific code separately while providing a single entry point. In **withPlugin.ts**, add the following code: ```ts withPlugin.ts const withPlugin: ConfigPlugin = config => { // Apply Android modifications first config = withAndroidPlugin(config); // Then apply iOS modifications and return return withIosPlugin(config); }; ``` ### Add TypeScript support and convert to dynamic app config We recommend writing config plugins in TypeScript, since this will provide intellisense for the configuration objects. However, your app config is ultimately evaluated by Node.js, which does not recognize TypeScript code by default. Therefore, you will need to add a parser for the TypeScript files from the the **plugins** directory to **app.config.ts** file. Install `tsx` library by running the following command: Then, change the static app config (**app.json**) to the [dynamic app config (**app.config.ts**)](/workflow/configuration/#dynamic-configuration) file. You can do this by renaming the **app.json** file to **app.config.ts** and changing the content of the file as shown below. Ensure to add the following import statement at the top of your **app.config.ts** file: ```ts app.config.ts module.exports = () => { /* @hide ... rest of your app config */ /* @end */ }; ``` ### Call the config plugin from your dynamic app config Now, you can call the config plugin from your dynamic app config. To do this, you need to add the path to the **withPlugin.ts** file to the plugins array in your app config: ```ts app.config.ts /* @info */ /* @end */ module.exports = /* @info */({ config }: { config: ExpoConfig })/* @end */ => { /* @hide ... rest of your app config */ /* @end */ /* @info */ plugins: [ ["./plugins/withPlugin.ts"], ], /* @end */ }; ``` To see the custom config applied in native projects, run the following command: To verify the custom config plugins applied, open **android/app/src/main/AndroidManifest.xml** and **ios/\<your-project-name\>/Info.plist** files: <CodeBlocksTable tabs={['AndroidManifest.xml', 'Info.plist']}> ```xml <manifest xmlns:android="http://schemas.android.com/apk/res/android"> <!-- ... rest of the configuration--> <application ...> <meta-data android:name="HelloWorldMessage" android:value="Hello world, from Expo plugin!"/> <!-- ... --> </application> </manifest> ``` ```xml <plist version="1.0"> <dict> <!-- ... --> <key>HelloWorldMessage</key> <string>Hello world, from Expo plugin!</string> <!-- ... --> </dict> </plist> ``` </CodeBlocksTable> ## Passing a parameter to a config plugin Your config plugin can accept parameters passed from your app config. To do so, you will need to read the parameter in your config plugin function, and then pass an object containing the parameter along with the config plugin function in your app config. Considering the previous example, let's pass a custom message to the plugin. Add an `options` object in **withAndroidPlugin.ts** and update the `message` variable to use the `options.message` property: {/* prettier-ignore */} ```ts withAndroidPlugin.ts /* @hide ...*/ /* @end */ type AndroidProps = { message?: string; }; const withAndroidPlugin: ConfigPlugin<AndroidProps> = ( config, /* @info Pass an <code>options</code> object to the plugin. */ options = {}/* @end */ ) => { /* @info Use the provided message or fall back to a default */ const message = options.message || 'Hello world, from Expo plugin!'; /* @end */ return withAndroidManifest(config, config => { /* @hide ... rest of the example remains unchanged */ /* @end */ }); }; ``` Similarly, add an `options` object in **withIosPlugin.ts** and update the `message` variable to use the `options.message` property: {/* prettier-ignore */} ```ts withIosPlugin.ts /* @hide ...*/ /* @end */ type IosProps = { message?: string; }; const withIosPlugin: ConfigPlugin<IosProps> = (config, /* @info Pass an <code>options</code> object to the plugin. */ options = {}/* @end */) => { /* @info Use the provided message or fall back to a default */ const message = options.message || 'Hello world, from Expo plugin!'; /* @end */ /* @hide ... rest of the example remains unchanged*/ /* @end */ }; ``` Update the **withPlugin.ts** file to pass the `options` object to both plugins: {/* prettier-ignore */} ```ts withPlugin.ts /* @hide ...*/ /* @end */ const withPlugin: ConfigPlugin<{ message?: string }> = (config, /* @info */ options = {}/* @end */) => { /* @info */ config = withAndroidPlugin(config, options); return withIosPlugin(config, options); /* @end */ }; ``` To pass a value dynamically to the plugin, you can pass an object with the `message` property to the plugin in your app config: ```ts app.config.ts { /* @hide ...*/ /* @end */ plugins: [ [ "./plugins/withPlugin.ts", { message: "Custom message from app.config.ts" }, ], ], } ``` ## Chaining config plugins Config plugins can be chained together to apply multiple modifications. Each plugin in the chain runs in the order it appears, with the output of one plugin becoming the input for the next. This sequential execution ensures that dependencies between plugins are respected and allows you to control the precise order of modifications to your native code. To chain config plugins, you can pass an array of plugins to the `plugins` array property in your app config. This is also supported in JSON app config file format (**app.json**). ```ts app.config.ts module.exports = ({ config }: { config: ExpoConfig }) => { name: 'my app', plugins: [ [withFoo, 'input 1'], [withBar, 'input 2'], [withDelta, 'input 3'], ], }; ``` The `plugins` array uses `withPlugins` method under the hood to chain the plugins. If your plugins array is getting long or has complex configuration, you can use the `withPlugins` method directly to make your configuration easier to read. `withPlugins` will chain the plugins together and execute them in order. ```ts app.config.ts // Create a base config object const baseConfig = { name: 'my app', /* @hide ... rest of the config */ /* @end */ }; // ❌ Hard to read withDelta(withFoo(withBar(config, 'input 1'), 'input 2'), 'input 3'); // ✅ Easy to read withPlugins(config, [ [withFoo, 'input 1'], [withBar, 'input 2'], // When no input is required, you can just pass the method withDelta, ]); // Export the base config with plugins applied module.exports = ({ config }: { config: ExpoConfig }) => { return withPlugins(baseConfig, plugins); }; ``` ## Using a config plugin Expo config plugins are usually included in Node.js modules. You can install them just like other libraries in your project. For example, `expo-camera` has a plugin that adds camera permissions to the **AndroidManifest.xml** and **Info.plist**. To install it in your project, run the following command: In your [app config](/versions/latest/config/app/), you can add `expo-camera` to the list of plugins: ```json app.json { "expo": { "plugins": ["expo-camera"] } } ``` Some config plugins offer flexibility by allowing you to pass options to customize their configuration. To do this, you can pass an array with the Expo library name as the first argument, and an object containing the options as the second argument. For example, the `expo-camera` plugin allows you to customize the camera permission message: ```json app.json { "expo": { "plugins": [ [ "expo-camera", { "cameraPermission": "Allow $(PRODUCT_NAME) to access your camera." } ] ] } } ``` > **info** **Tip**: For every Expo library that has a config plugin, you'll find more information about that in the library's API reference. For example, the [`expo-camera` library has a config plugin section](/versions/latest/sdk/camera/#configuration-in-appjsonappconfigjs). On running the `npx expo prebuild`, the [`mods`](/config-plugins/introduction/#mods) are compiled, and the native files change. The changes don't take effect until you rebuild the native project, for example, with Xcode. **If you're using config plugins in a project without native directories (CNG projects), they will be applied during the prebuild step in EAS Build** or when running `npx expo prebuild|android|ios` locally.