Config Plugins en CNG

Q: ¿Dónde se ejecutan los config plugins?

En tiempo de prebuild en la máquina que ejecuta expo prebuild o EAS Build - no en cada recarga de Metro. Reconstruye binarios nativos después de cambios de plugins que afecten derechos o deps nativos.

Q: ¿Cómo pruebo un plugin sin una compilación completa?

npx expo config --type introspect muestra resultados de mod. Para validación final, ejecuta prebuild dos veces y confirma cero diferencias.

Q: ¿Cuál es la diferencia entre plugins de app.config y la página de config-plugins de módulos nativos?

Esta página se enfoca en flujo de trabajo CNG - composición, idempotencia y supervivencia de prebuild. ../native-modules/config-plugins/config-plugins.md cubre la superficie de API para autores de módulos.

Cambios nativos componibles que sobreviven a expo prebuild --clean (el predeterminado de SDK 57). Los config plugins codifican permisos, derechos, dependencias de Gradle y entradas de manifiesto en TypeScript controlado por versiones - no en clics editados manualmente en Xcode.

Receta

Tarjeta de receta de referencia rápida - lista para copiar-pegar.

npx expo install @expo/config-plugins
mkdir -p plugins

// plugins/withMyFeature.ts
import {
  ConfigPlugin,
  withInfoPlist,
  withAndroidManifest,
  AndroidConfig,
} from "expo/config-plugins";
 
const withMyFeature: ConfigPlugin = (config) => {
  config = withInfoPlist(config, (cfg) => {
    cfg.modResults.NSMyFeatureUsageDescription =
      "Allow $(PRODUCT_NAME) to use My Feature.";
    return cfg;
  });
 
  config = withAndroidManifest(config, (cfg) => {
    const main = AndroidConfig.Manifest.getMainApplicationOrThrow(cfg.modResults);
    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
      main,
      "com.example.MY_FEATURE_ENABLED",
      "true"
    );
    return cfg;
  });
 
  return config;
};
 
export default withMyFeature;

// app.config.ts
import type { ExpoConfig } from "expo/config";
import withMyFeature from "./plugins/withMyFeature";
 
const config: ExpoConfig = {
  name: "MyApp",
  slug: "my-app",
  plugins: [
    "expo-router",
    withMyFeature,
    [
      "expo-build-properties",
      { ios: { deploymentTarget: "15.1" } },
    ],
  ],
};
 
export default config;

npx expo prebuild --no-install
npx expo prebuild --no-install   # segunda ejecución: git diff ios android debe estar vacío

Cuándo usar esto:

Añadiendo descripciones de uso de iOS o permisos de Android
Conectando claves de SDK de terceros en Info.plist / AndroidManifest.xml
Ajustando minSdkVersion de Gradle, destino de implementación de iOS o reglas de ProGuard
Portando ediciones nativas brownfield en CNG reproducible

Ejemplo en funcionamiento

Una pila de plugins componible para una app que necesita acceso a la cámara, un esquema de URL personalizado y un destino de implementación compartido - configuración típica de producción de SDK 57.

// plugins/withAppLinks.ts
import { ConfigPlugin, withEntitlementsPlist } from "expo/config-plugins";
 
const withAppLinks: ConfigPlugin<{ domain: string }> = (config, { domain }) => {
  return withEntitlementsPlist(config, (cfg) => {
    const key = "com.apple.developer.associated-domains";
    const existing = (cfg.modResults[key] as string[] | undefined) ?? [];
    const entry = `applinks:${domain}`;
    if (!existing.includes(entry)) {
      cfg.modResults[key] = [...existing, entry];
    }
    return cfg;
  });
};
 
export default withAppLinks;

// app.config.ts
import type { ExpoConfig } from "expo/config";
import withAppLinks from "./plugins/withAppLinks";
 
const config: ExpoConfig = {
  name: "Shop",
  slug: "shop",
  scheme: "shop",
  ios: {
    bundleIdentifier: "com.example.shop",
  },
  android: {
    package: "com.example.shop",
  },
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission: "Scan product barcodes in the store.",
      },
    ],
    [withAppLinks, { domain: "shop.example.com" }],
    [
      "expo-build-properties",
      {
        ios: { deploymentTarget: "15.1" },
        android: { minSdkVersion: 24 },
      },
    ],
  ],
};
 
export default config;

# Valida la salida del plugin sin compilación completa
npx expo config --type introspect
 
# Genera y verifica idempotencia
rm -rf ios android
npx expo prebuild --no-install
npx expo prebuild --no-install

Lo que esto demuestra:

Plugin de biblioteca primero - expo-camera posee las cadenas de permiso de cámara
Plugin personalizado parametrizado - withAppLinks acepta domain y deduplica derechos
Propiedades de compilación al final - expo-build-properties ajusta versiones de herramientas después de plugins de características
Idempotencia - el dominio asociado se añade solo si falta

Análisis profundo

Cómo funcionan los Config Plugins

app.config.ts  ->  expo prebuild  ->  @expo/prebuild-config  ->  config plugins (mods)  ->  ios/ android/

Evaluación: Expo carga app.config.ts y resuelve el array de plugins (cadenas, tuplas o funciones).
Pipeline de mod: Cada plugin recibe ExpoConfig y retorna config modificado mediante helpers with* (withInfoPlist, withGradleProperties, etc.).
Merge de plantilla: Los archivos de plantilla SDK 57 se copian, luego los mods se aplican en orden de plugins.
Regen limpia: El prebuild predeterminado borra carpetas primero - solo los cambios codificados en plugins persisten.

Patrones de composición

Patrón	Usar cuando
Plugin de cadena `"expo-router"`	La biblioteca incluye un plugin sin configuración
Tupla `["expo-camera", { ... }]`	El plugin de biblioteca necesita opciones
Función `withMyFeature`	Mutación nativa personalizada
Tupla + función `[withAppLinks, { domain }]`	Plugin personalizado con parámetros
`withPlugins(config, [a, b, c])`	Agrupa mods relacionados en un archivo

// plugins/index.ts - compone mods relacionados
import { ConfigPlugin, withPlugins } from "expo/config-plugins";
import withAppLinks from "./withAppLinks";
import withPushEnvironment from "./withPushEnvironment";
 
const withNativeStack: ConfigPlugin = (config) =>
  withPlugins(config, [
    [withAppLinks, { domain: "shop.example.com" }],
    [withPushEnvironment, { env: "production" }],
  ]);
 
export default withNativeStack;

Reglas de orden de plugins

Los plugins que crean estructura base se ejecutan antes de plugins que parchean el mismo archivo
Derechos antes de características que dependen de ellos
expo-build-properties a menudo se ejecuta tarde - el destino de implementación afecta otros pods
Al depurar, biseca el array de plugins - elimina la mitad hasta que prebuild tenga éxito

Lista de verificación de idempotencia

Anti-patrón	Solución
Añadir el mismo XML cada ejecución	Verifica si el nodo existe antes de `add`
Claves `NSCameraUsageDescription` duplicadas	Fusiona en clave existente o usa plugin de biblioteca
Reemplazo de regex sin ancla	Usa mods estructurados (`withInfoPlist`) no archivos de texto
Gradle `apply plugin` global dos veces	Protege con `if (!contents.includes(...))`

Depuración

# Ve mods resueltos sin escribir ios/android
npx expo config --type introspect
 
# Diff después del cambio de plugin
rm -rf ios android && npx expo prebuild --no-install
git diff ios   # si está rastreado; equipos CNG inspeccionan en IDE
 
# Doctor detecta config de plugin inválido
npx expo-doctor

Errores comunes

Editar ios/ después de prebuild - El predeterminado limpio de SDK 57 borra cambios. Solución: Codifica en un plugin.
Orden de plugin incorrecto - Posterior plugin sobrescribe clave Info.plist anterior. Solución: Documenta el orden; usa introspect.
Append no idempotente - Segunda ejecución de prebuild duplica entradas de manifiesto. Solución: Verifica existencia antes de añadir.
npm install para paquetes de plugins - Desviación de versión vs binarios nativos SDK 57. Solución: npx expo install.
Probar solo en Expo Go - Los plugins que afectan derechos necesitan reconstrucción del cliente de desarrollo. Solución: expo run:ios después de que el plugin se fusione.
Importar desde ruta equivocada - Usa expo/config-plugins en plugins de app; las bibliotecas usan @expo/config-plugins por documentación de paquete.

Alternativas

Alternativa	Usar cuando	No usar cuando
Config plugin (recomendado)	Cualquier cambio nativo repetible bajo CNG	Experimento local único sin ruta de producción
Plugin integrado de biblioteca	El paquete documenta entrada de `plugins`	La biblioteca no tiene plugin de SDK 57 - fork o ADR
`expo-build-properties`	Versiones de SDK, ProGuard, destino de implementación	XML de manifiesto complejo - escribe un plugin personalizado
Carpetas nativas confirmadas (brownfield)	App heredada sin ruta de migración de plugins	Apps greenfield de SDK 57 - usa CNG
`patch-package` en archivos generados	Hotfix de emergencia con ADR	Flujo de trabajo estándar - parches perdidos en prebuild limpio

FAQs

¿Dónde se ejecutan los config plugins?

En tiempo de prebuild en la máquina que ejecuta expo prebuild o EAS Build - no en cada recarga de Metro. Reconstruye binarios nativos después de cambios de plugins que afecten derechos o deps nativos.

¿Puedo usar config plugins sin confirmar ios/?

Sí - ese es el predeterminado de CNG. Los plugins son la fuente de verdad; las carpetas nativas son salida efímera.

¿Cómo pruebo un plugin sin una compilación completa?

npx expo config --type introspect muestra resultados de mod. Para validación final, ejecuta prebuild dos veces y confirma cero diferencias.

¿Cuál es la diferencia entre plugins de app.config y la página de config-plugins de módulos nativos?

Esta página se enfoca en flujo de trabajo CNG - composición, idempotencia y supervivencia de prebuild. ../native-modules/config-plugins/config-plugins.md cubre la superficie de API para autores de módulos.

Relacionado

Prebuild Basics - lo que prebuild genera
expo prebuild Workflow - regen limpia y lista de verificación de iteración local
../native-modules/config-plugins/config-plugins.md - API de plugins para autores de módulos nativos
../native-modules/patching-native-projects/patching-native-projects.md - cuándo los parches son inevitables
../expo-rules/native-module-rules/native-module-rules.md - reglas de instalación y plugins de Tier 2
Custom Native Code in CNG - expo run:ios/android después de que los plugins se implementen

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).

Receta

Tarjeta de receta de referencia rápida - lista para copiar-pegar.

npx expo install @expo/config-plugins
mkdir -p plugins

// plugins/withMyFeature.ts
import {
  ConfigPlugin,
  withInfoPlist,
  withAndroidManifest,
  AndroidConfig,
} from "expo/config-plugins";
 
const withMyFeature: ConfigPlugin = (config) => {
  config = withInfoPlist(config, (cfg) => {
    cfg.modResults.NSMyFeatureUsageDescription =
      "Allow $(PRODUCT_NAME) to use My Feature.";
    return cfg;
  });
 
  config = withAndroidManifest(config, (cfg) => {
    const main = AndroidConfig.Manifest.getMainApplicationOrThrow(cfg.modResults);
    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
      main,
      "com.example.MY_FEATURE_ENABLED",
      "true"
    );
    return cfg;
  });
 
  return config;
};
 
export default withMyFeature;

// app.config.ts
import type { ExpoConfig } from "expo/config";
import withMyFeature from "./plugins/withMyFeature";
 
const config: ExpoConfig = {
  name: "MyApp",
  slug: "my-app",
  plugins: [
    "expo-router",
    withMyFeature,
    [
      "expo-build-properties",
      { ios: { deploymentTarget: "15.1" } },
    ],
  ],
};
 
export default config;

npx expo prebuild --no-install
npx expo prebuild --no-install   # segunda ejecución: git diff ios android debe estar vacío

Cuándo usar esto:

Añadiendo descripciones de uso de iOS o permisos de Android
Conectando claves de SDK de terceros en Info.plist / AndroidManifest.xml
Ajustando minSdkVersion de Gradle, destino de implementación de iOS o reglas de ProGuard
Portando ediciones nativas brownfield en CNG reproducible

Ejemplo en funcionamiento

// plugins/withAppLinks.ts
import { ConfigPlugin, withEntitlementsPlist } from "expo/config-plugins";
 
const withAppLinks: ConfigPlugin<{ domain: string }> = (config, { domain }) => {
  return withEntitlementsPlist(config, (cfg) => {
    const key = "com.apple.developer.associated-domains";
    const existing = (cfg.modResults[key] as string[] | undefined) ?? [];
    const entry = `applinks:${domain}`;
    if (!existing.includes(entry)) {
      cfg.modResults[key] = [...existing, entry];
    }
    return cfg;
  });
};
 
export default withAppLinks;

// app.config.ts
import type { ExpoConfig } from "expo/config";
import withAppLinks from "./plugins/withAppLinks";
 
const config: ExpoConfig = {
  name: "Shop",
  slug: "shop",
  scheme: "shop",
  ios: {
    bundleIdentifier: "com.example.shop",
  },
  android: {
    package: "com.example.shop",
  },
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission: "Scan product barcodes in the store.",
      },
    ],
    [withAppLinks, { domain: "shop.example.com" }],
    [
      "expo-build-properties",
      {
        ios: { deploymentTarget: "15.1" },
        android: { minSdkVersion: 24 },
      },
    ],
  ],
};
 
export default config;

# Valida la salida del plugin sin compilación completa
npx expo config --type introspect
 
# Genera y verifica idempotencia
rm -rf ios android
npx expo prebuild --no-install
npx expo prebuild --no-install

Lo que esto demuestra:

Plugin de biblioteca primero - expo-camera posee las cadenas de permiso de cámara
Plugin personalizado parametrizado - withAppLinks acepta domain y deduplica derechos
Propiedades de compilación al final - expo-build-properties ajusta versiones de herramientas después de plugins de características
Idempotencia - el dominio asociado se añade solo si falta

Análisis profundo

Cómo funcionan los Config Plugins

app.config.ts  ->  expo prebuild  ->  @expo/prebuild-config  ->  config plugins (mods)  ->  ios/ android/

Evaluación: Expo carga app.config.ts y resuelve el array de plugins (cadenas, tuplas o funciones).
Pipeline de mod: Cada plugin recibe ExpoConfig y retorna config modificado mediante helpers with* (withInfoPlist, withGradleProperties, etc.).
Merge de plantilla: Los archivos de plantilla SDK 57 se copian, luego los mods se aplican en orden de plugins.
Regen limpia: El prebuild predeterminado borra carpetas primero - solo los cambios codificados en plugins persisten.

Patrones de composición

Patrón	Usar cuando
Plugin de cadena `"expo-router"`	La biblioteca incluye un plugin sin configuración
Tupla `["expo-camera", { ... }]`	El plugin de biblioteca necesita opciones
Función `withMyFeature`	Mutación nativa personalizada
Tupla + función `[withAppLinks, { domain }]`	Plugin personalizado con parámetros
`withPlugins(config, [a, b, c])`	Agrupa mods relacionados en un archivo

// plugins/index.ts - compone mods relacionados
import { ConfigPlugin, withPlugins } from "expo/config-plugins";
import withAppLinks from "./withAppLinks";
import withPushEnvironment from "./withPushEnvironment";
 
const withNativeStack: ConfigPlugin = (config) =>
  withPlugins(config, [
    [withAppLinks, { domain: "shop.example.com" }],
    [withPushEnvironment, { env: "production" }],
  ]);
 
export default withNativeStack;

Reglas de orden de plugins

Los plugins que crean estructura base se ejecutan antes de plugins que parchean el mismo archivo
Derechos antes de características que dependen de ellos
expo-build-properties a menudo se ejecuta tarde - el destino de implementación afecta otros pods
Al depurar, biseca el array de plugins - elimina la mitad hasta que prebuild tenga éxito

Lista de verificación de idempotencia

Anti-patrón	Solución
Añadir el mismo XML cada ejecución	Verifica si el nodo existe antes de `add`
Claves `NSCameraUsageDescription` duplicadas	Fusiona en clave existente o usa plugin de biblioteca
Reemplazo de regex sin ancla	Usa mods estructurados (`withInfoPlist`) no archivos de texto
Gradle `apply plugin` global dos veces	Protege con `if (!contents.includes(...))`

Depuración

# Ve mods resueltos sin escribir ios/android
npx expo config --type introspect
 
# Diff después del cambio de plugin
rm -rf ios android && npx expo prebuild --no-install
git diff ios   # si está rastreado; equipos CNG inspeccionan en IDE
 
# Doctor detecta config de plugin inválido
npx expo-doctor

Errores comunes

Editar ios/ después de prebuild - El predeterminado limpio de SDK 57 borra cambios. Solución: Codifica en un plugin.
Orden de plugin incorrecto - Posterior plugin sobrescribe clave Info.plist anterior. Solución: Documenta el orden; usa introspect.
Append no idempotente - Segunda ejecución de prebuild duplica entradas de manifiesto. Solución: Verifica existencia antes de añadir.
npm install para paquetes de plugins - Desviación de versión vs binarios nativos SDK 57. Solución: npx expo install.
Probar solo en Expo Go - Los plugins que afectan derechos necesitan reconstrucción del cliente de desarrollo. Solución: expo run:ios después de que el plugin se fusione.
Importar desde ruta equivocada - Usa expo/config-plugins en plugins de app; las bibliotecas usan @expo/config-plugins por documentación de paquete.

Alternativas

Alternativa	Usar cuando	No usar cuando
Config plugin (recomendado)	Cualquier cambio nativo repetible bajo CNG	Experimento local único sin ruta de producción
Plugin integrado de biblioteca	El paquete documenta entrada de `plugins`	La biblioteca no tiene plugin de SDK 57 - fork o ADR
`expo-build-properties`	Versiones de SDK, ProGuard, destino de implementación	XML de manifiesto complejo - escribe un plugin personalizado
Carpetas nativas confirmadas (brownfield)	App heredada sin ruta de migración de plugins	Apps greenfield de SDK 57 - usa CNG
`patch-package` en archivos generados	Hotfix de emergencia con ADR	Flujo de trabajo estándar - parches perdidos en prebuild limpio

FAQs

¿Dónde se ejecutan los config plugins?

¿Puedo usar config plugins sin confirmar ios/?

Sí - ese es el predeterminado de CNG. Los plugins son la fuente de verdad; las carpetas nativas son salida efímera.

¿Cómo pruebo un plugin sin una compilación completa?

npx expo config --type introspect muestra resultados de mod. Para validación final, ejecuta prebuild dos veces y confirma cero diferencias.

¿Cuál es la diferencia entre plugins de app.config y la página de config-plugins de módulos nativos?

Relacionado

Prebuild Basics - lo que prebuild genera
expo prebuild Workflow - regen limpia y lista de verificación de iteración local
../native-modules/config-plugins/config-plugins.md - API de plugins para autores de módulos nativos
../native-modules/patching-native-projects/patching-native-projects.md - cuándo los parches son inevitables
../expo-rules/native-module-rules/native-module-rules.md - reglas de instalación y plugins de Tier 2
Custom Native Code in CNG - expo run:ios/android después de que los plugins se implementen

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).

Config Plugins en CNG

Buscar en la documentación

Config Plugins en CNG