expo/config-plugins: a waiting room for libraries that have not caught up

What a config plugin actually does

This repository is a collection of assorted Expo config plugins for configuring the npx expo prebuild command, and the overview states its purpose plainly: it is meant to be a temporary home for packages that do not have a built-in config plugin. The reason this exists at all is that a React Native project usually has no native project checked in. Instead, the native Android and iOS projects are generated from the JavaScript side by the prebuild step, and a library that needs a manifest entry, a permission or a Gradle tweak has to hook into that generation. A config plugin is the mechanism for doing so. Without one, a library either asks you to edit the native project by hand, which prebuild will overwrite on the next run, or it does nothing and the feature quietly does not work.

The three rules that keep this from becoming a junk drawer

The repository states three policies, and they are the interesting part of the design. First, packages are preferred to ship their own Expo config plugin, because that keeps plugin and package versions always aligned and makes new features available in both the package and the plugin simultaneously; if packages have not adopted config plugins yet, the community can add one here as a temporary home. Second, all packages here are community maintained and not maintained by Expo, with an invitation to improve the docs, packages and tests. Third, and this is the rule that shapes the whole structure, the maintainers keep a one-to-one mapping between native packages and the @config-plugins packages, which means there should be no general utility packages here, since those are better suited to a different repository or npm namespace. That last rule is why the repository is small and why it will stay small.

The repository layout, and what the scripts do

The top level shows a pnpm workspace with a packages/ directory holding the individual plugins, an apps/ directory, a fixtures/ directory, and scripts/ for repository automation. The root package manifest is private and named for the repository rather than for a published package, and its scripts describe the workflow. A gen script runs a TypeScript generator for plugins, a bump script patches the version across all packages without git tagging, and a release script publishes recursively across the packages. The start script builds every package in parallel in watch mode, and prepare runs across the packages as well. The formatting and linting are handled by oxfmt and oxlint with a config file for the scripts directory, and the repository declares pnpm as its package manager at version 12.2.1 in both the engines and the devEngines fields, with the latter set to warn rather than fail on a mismatch.

The release script, and why the version bump is separate

Two of the root scripts show how a monorepo of plugins is published.

    "bump": "pnpm --filter './packages/*' -r exec pnpm version patch --no-git-tag-version",
    "release": "pnpm publish -r --filter './packages/*'",

The bump script runs the version command across every package under packages, patching the version and passing the no-git-tag-version flag so the tags are left to the release tooling rather than created by npm. The release script then publishes recursively, restricted to those same packages. Splitting the two is deliberate: the version numbers of the individual plugins and the act of putting them on the registry are separate concerns, and a monorepo with a dozen packages needs to be able to move one of them without touching the rest. The prepare script builds all the packages in parallel before publishing, which is the step that guarantees a published plugin contains the code its version claims.

Where to look for a plugin that is not here

The overview answers the question of where to look for other config plugins, and the answer is not this repository. Many React Native libraries ship their own built-in config plugins, and the pointer for finding them is the React Native Directory. That is a meaningful division. A library that has adopted the config plugin system has a maintainer who is paid to keep it working against each new Expo release, and a plugin in this repository is maintained by whoever contributed it, with no such guarantee. The description of the repository says the same thing in its title, community maintained Expo config plugins for packages that have not adopted the config plugin system yet, so the two sources are complementary rather than competing. The releases listed for the repository are individual plugin packages rather than the repository itself, and the dated ones in the list are from 2022, which is a fair indication of how little churn most of these plugins see.

What is in the repository today

The published packages visible in the release list are named after the libraries they serve, in the @config-plugins scope, and they include react-native-webrtc and react-native-quick-actions. The naming convention is the point: a plugin is published under the scope rather than under the name of the library it configures, because the plugin is a separate package with a separate version and its own maintainers. The repository also ships a CLAUDE.md file for automated tooling, a jest base configuration, a shared tsconfig, an oxlint configuration, a remark setup with link validation, and a pnpm workspace file. The presence of a link validator in the scripts is a small sign of care, because a catalogue of links to other people's repositories goes stale quickly, and a build that fails on a dead link is a build that tells you a plugin's upstream has moved.

Editorial conclusion

expo/config-plugins fits a React Native developer whose chosen library needs a native change during expo prebuild and whose maintainers have not shipped a config plugin, because here is a maintained plugin for that specific package rather than a hand-edited native project. It does not fit a project that needs several unrelated native tweaks at once, because the repository's own rule is one-to-one between native packages and config plugin packages, and general utility packages are explicitly better suited to another repository or namespace. It also does not fit anyone who wants an Expo maintained plugin, since everything here is community maintained and not maintained by Expo. Before you depend on one, check whether the library has since shipped its own plugin, because the stated preference is for packages to ship their own so versions stay aligned, and read the contributing guide before adding anything, since the mapping rule is enforced by review.

Frequently asked questions

Official sources

1. expo/config-plugins on GitHub
2. Issues
3. README
4. Releases