When an Expo app config lists a library name in plugins, how does Expo find that library's config plugin, and why do libraries ship app.plugin.js?

## How a plugin entry becomes a function An entry in the Expo app config's `plugins` array is usually a **string**. Before prebuild can run it, `@expo/config-plugins` must turn that string into a JavaScript function. The resolver follows a fixed order: 1. **A file reference is loaded as-is.** A relative path such as `./plugins/withMapsKey.js`, or a specifier with a file path such as `some-package/plugin.js`, resolves directly to that file. 2. **A package name looks for `app.plugin` at the package root.** For `expo-location`, the resolver tries `expo-location/app.plugin` with the extensions `.js`, `.cjs`, `.mjs`, `.ts`, `.cts` and `.mts`, in that order. 3. **Otherwise it falls back to the package's `main` entry.** If there is no `app.plugin` file, the package's normal entry point is loaded and treated as the plugin. If nothing resolves, prebuild fails with a "Failed to resolve plugin for module" error that asks whether node modules are installed. If a package resolves but does not export a function, the error says the package "does not contain a valid config plugin". ## Why `app.plugin.js` exists A library's `main` entry is **runtime code**: React Native components, imports of native modules, often ESM or syntax that needs Metro's transforms. The app config is evaluated by **Node.js** at build time. Loading that runtime entry in Node would often crash, and even when it works, it is the wrong code. `app.plugin.js` gives the library a separate, **Node-only entry** for configuration. `expo-location`, for example, ships an `app.plugin.js` that simply re-exports its compiled plugin: ```js module.exports = require('./plugin/build/withLocation'); ``` So the same package name means two different things in two places: | Where the name appears | What loads | |---|---| | `import * as Location from 'expo-location'` in app code | The runtime entry, bundled by Metro for the device | | `"expo-location"` in the `plugins` array | `app.plugin.js`, run by Node during config evaluation | ## Consequences for app developers - **Use the package name, not a deep path.** Pointing `plugins` at a file inside the package, such as its build folder, bypasses the resolution order; Expo documents this as not recommended because internal paths can change between versions. - **A package without a plugin cannot simply be listed.** If its main entry does not export a plugin function, prebuild fails, so check the library's documentation before adding it. - **`npx expo install` helps.** When the installed package ships an `app.plugin` file, `npx expo install` adds it to the `plugins` array (without options) if it is not listed already, skipping the few plugins Expo applies automatically. A plain package-manager install does not. - **Options still need the tuple.** `["expo-location", { ... }]` passes options; a bare object after the string fails with an error telling you to wrap the plugin configuration in square brackets. ## Consequences for library authors - **Ship `app.plugin.js` at the package root** and keep it free of React Native imports. - **Compile TypeScript plugins** to JavaScript before publishing, the way `expo-location` requires `plugin/build/...`; the resolver accepts `.ts` files, but a published package should not depend on the consumer being able to load TypeScript. - **Make the plugin idempotent**, because apps re-run prebuild. - **Validate options** and throw a clear error on bad input, so users do not debug a broken manifest instead. ## Local plugins in an app For a delivery app that needs a setting no library provides, a **local plugin** is just a file referenced by path: ```json { "expo": { "plugins": ["./plugins/withDeliveryZones.js"] } } ``` It resolves by rule 1, runs in Node, and follows the same ordering rules as package plugins. Writing its mods is a separate topic; applying it is only the path in the array. This resolution order is implemented in `@expo/config-plugins` in Expo SDK 57.