Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 38 ยท Getting Started

Prebuild and Config Plugins

Understand Continuous Native Generation: how expo prebuild creates ios and android folders from your config, and how config plugins and mods edit native files safely.

React Native apps contain two native projects: an Xcode project (ios/) and a Gradle project (android/). Maintaining them by hand is painful: every SDK upgrade means merging changes, and every library asks you to edit Info.plist, AndroidManifest.xml or MainApplication. Expo's answer is Continuous Native Generation (CNG): treat the native folders as build output generated from your project, not as source code you edit.

The commands and plugin code below are read-only (they need the real Expo toolchain). Live stand-ins model how config plugins transform a native config.

What expo prebuild does

Terminal
npx expo prebuild

Prebuild reads app.json, your installed packages and plugins, then generates ios/ and android/ from a template for your SDK version, applying every plugin on top. npx expo run:android and run:ios call it automatically when the folders are missing. Useful flags:

Terminal
npx expo prebuild --clean            # delete and regenerate (discard manual edits)
npx expo prebuild --platform ios
npx expo prebuild --no-install       # do not run pod install
flowchart LR
  A["app.json / app.config.ts"] --> P["expo prebuild"]
  B["package.json<br/>(libraries)"] --> P
  C["Config plugins"] --> P
  T["Native template<br/>for your SDK"] --> P
  P --> I["ios/"]
  P --> D["android/"]

The native folders are generated output, so add them to .gitignore.

Benefits: SDK upgrades are mostly "change the version, run prebuild --clean"; native setup of libraries is automatic; your repo stays small. EAS Build runs prebuild for you in the cloud, so with CNG you may never create the folders locally at all.

If you edit ios/ or android/ by hand and then run prebuild --clean, your edits are lost. Put such changes into a config plugin instead, so they are repeatable.

Config plugins

A config plugin is a function that receives the Expo config and returns a modified one, usually by registering mods. A mod is a function that edits one native file in a safe, structured way (a parsed Info.plist, an AndroidManifest object, a Gradle file). Libraries ship their own plugins, which you enable in app.json:

JSON
{
  "expo": {
    "plugins": [
      "expo-router",
      ["expo-camera", { "cameraPermission": "Allow $(PRODUCT_NAME) to take photos." }],
      ["expo-location", { "locationWhenInUsePermission": "We show nearby trails." }]
    ]
  }
}

An entry is a package name, or [name, options]. For the camera entry, the plugin writes NSCameraUsageDescription into the iOS Info.plist and adds android.permission.CAMERA to the Android manifest. You never touch those files.

Writing a plugin

Plugins use helpers from expo/config-plugins:

TypeScript
// plugins/with-app-queries.ts
import { ConfigPlugin, withInfoPlist, withAndroidManifest } from 'expo/config-plugins';

const withMyPlugin: ConfigPlugin<{ scheme: string }> = (config, { scheme }) => {
  config = withInfoPlist(config, (c) => {
    const list = (c.modResults.LSApplicationQueriesSchemes ??= []);
    if (!list.includes(scheme)) list.push(scheme);
    return c;
  });
  config = withAndroidManifest(config, (c) => {
    c.modResults.manifest['uses-permission'] ??= [];
    return c;
  });
  return config;
};

export default withMyPlugin;

Then reference it: "plugins": [["./plugins/with-app-queries", { "scheme": "whatsapp" }]]. Two rules make plugins trustworthy:

  1. Be idempotent: running prebuild twice must produce the same result (check before you add).
  2. Compose, do not overwrite: modify only what you need and return the config.
JS A config plugin, modeled

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the duplicate plugin did not duplicate the scheme. That is idempotency at work.

The mod stages

Mods run in a fixed order. Plugins can be written for two kinds of files:

  • Dangerous mods (withDangerousMod): run arbitrary code against the file system, for example to copy a file into android/app. First in the order; use sparingly.
  • Introspective mods (withInfoPlist, withAndroidManifest, withAppBuildGradle, withXcodeProject, withMainApplication): receive a parsed model to edit.
  • Finalize stage: runs last, for post-processing.

Plugin options are plain JSON, so a plugin is configured entirely from app.json, which keeps the whole native setup reviewable in one file.

JS Apply merge rules to a manifest

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical workflow

  1. Add a library: npx expo install expo-camera.
  2. Add its plugin to app.json with the options it documents.
  3. Run npx expo prebuild --clean (or let run:android do it).
  4. Rebuild the development build and run.
  5. Commit app.json and plugin files, not the generated folders.

Common mistakes

  • Editing ios/ or android/ directly and committing only part of it, then losing it on a clean prebuild.
  • Forgetting the plugin entry, so the library crashes with a missing permission or missing native module.
  • Expecting Expo Go to honor plugin changes. Plugins affect native code, so they need a development or production build.
  • Writing a non-idempotent plugin that adds a line every prebuild.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Continuous Native Generation mean?

    CNG treats ios/ and android/ as generated output of your config, plugins and the SDK template.
  2. 2. What is a config plugin?

    Config plugins register mods that edit Info.plist, AndroidManifest and similar files.
  3. 3. Why should a plugin be idempotent?

    Running prebuild twice must not duplicate entries or break files.
  4. 4. Where should you put a native change you want to keep?

    Manual edits are lost on prebuild --clean; a plugin reproduces the change every time.

Summary

  • expo prebuild generates ios/ and android/ from your config, libraries and plugins.
  • Treat the native folders as build output and ignore them in Git.
  • Config plugins edit native files through mods and must be idempotent.
  • Plugin changes need a new native build; Expo Go cannot pick them up.

Next: File-Based Routing