How would you write an Expo config plugin that adds an iOS App Groups entitlement and an Android manifest meta-data entry idempotently?

## The task A common reason to write a config plugin is a feature that needs native setup on both platforms. Suppose an app ships a home-screen widget that must read data the app writes. On iOS the app and the widget share storage through an **App Group**, which is an entitlement on the app target. On Android, a native SDK in the project reads the same group identifier from a `<meta-data>` element inside `<application>` in `AndroidManifest.xml`. The goal is a plugin that sets both from one prop and can be run any number of times. If the entitlement were static, `ios.entitlements` in app config could set it without any plugin. A plugin earns its place when a library must apply the setting for its users, or when the value is computed from props. ## Structure: one plugin function per platform Keep the platform halves separate and compose them: 1. `withAppGroupEntitlement` uses `withEntitlementsPlist`. 2. `withAppGroupMetaData` uses `withAndroidManifest`. 3. `withAppGroup` applies both with `withPlugins(config, [[a, props], [b, props]])`, which applies the list in order. Splitting them keeps each mod small, lets each be unit-tested against a fixture object, and makes debug output name the half that failed. ## The iOS half: withEntitlementsPlist `withEntitlementsPlist` registers a mod on `mods.ios.entitlements`. When prebuild runs it: - locates the app target's `.entitlements` file, creating one from a template if needed; - parses it into a JS object and merges in `ios.entitlements` from app config; - passes that object to your callback as `config.modResults`; - after your callback, copies `modResults` back into `config.ios.entitlements` and writes the plist. The App Groups entitlement key is `com.apple.security.application-groups`, and its value is an **array of group identifiers**. So the callback reads the existing array (or an empty one), adds the group only if it is absent, and assigns it back. Overwriting the array would silently drop a group another plugin or the app config already added; blindly pushing would duplicate it. Because the entitlements mod supports **introspection**, EAS Build can read the final entitlements without generating the project and then synchronize the matching capabilities on the Apple Developer Console before building. App Groups is one of the capabilities it supports. ## The Android half: withAndroidManifest `withAndroidManifest` hands you the manifest parsed by xml2js: elements become arrays of objects, and attributes live under a `$` key, so `<application>` is `modResults.manifest.application[0]`. You can walk that shape by hand, but `expo/config-plugins` exports helpers under `AndroidConfig.Manifest` that encode the edge cases: | Helper | What it does | |---|---| | `getMainApplicationOrThrow(manifest)` | Returns the `<application>` element, throwing a clear error if the template lacks one | | `addMetaDataItemToMainApplication(app, name, value)` | Updates the `<meta-data>` with that `android:name`, or adds it if absent | | `removeMetaDataItemFromMainApplication(app, name)` | Removes it, useful when a prop is turned off | | `AndroidConfig.Permissions.ensurePermission(manifest, name)` | Adds a `<uses-permission>` only if missing | The value of the helper is **idempotency**: pushing a new object onto `mainApplication['meta-data']` works on the first run and duplicates the element on every later one. ## Why idempotency is the whole point `npx expo prebuild --clean` deletes the native folders and starts from the template, so a careless plugin looks fine there. Plain `npx expo prebuild` **layers onto existing files**: the base mods read the current `Info.plist`, entitlements and manifest from disk, including what your plugin wrote last time. A correct plugin therefore has to: - check before adding (arrays, `<meta-data>`, permissions); - update in place rather than append when a value changes; - never assume it is the only writer of a shared array. Standard mods such as these can run repeatedly with the same result when written this way; that is the property that lets teams run prebuild without `--clean` during development. ## Common mistakes - Reaching for `withDangerousMod` because `AndroidManifest.xml` is XML: the typed manifest mod already parses it and survives template changes far better than a regex. - Forgetting to **return `config`** from one of the callbacks, which breaks the mod chain with an error naming the mod. - Adding platform checks by hand: a mod registered on the iOS side only runs when iOS is prebuilt, so it needs no check of `modRequest.platform`. - Hard-coding the group identifier instead of taking it as a prop, which forces a code change per app or per environment. ## Checking the result - `npx expo prebuild --no-install` and inspect the generated files. - `npx expo config --type introspect` shows the evaluated entitlements and manifest under `_internal.modResults` without writing anything. - Run prebuild twice in a row and diff: the second run must change nothing.