Plugins de Configuração no CNG

Q: Onde os plugins de configuração são executados?

No tempo de prebuild na máquina que executa expo prebuild ou EAS Build - não a cada recarga do Metro. Reconstrua os binários nativos após alterações de plugin que afetam entitlements ou dependências nativas.

Q: Como testo um plugin sem uma compilação completa?

npx expo config --type introspect mostra os resultados dos mods. Para validação final, execute o prebuild duas vezes e confirme zero diff.

Q: Qual a diferença entre os plugins de app.config e a página de config-plugins de native-modules?

Esta página foca no fluxo de trabalho CNG - composição, idempotência e sobrevivência ao prebuild. ../native-modules/config-plugins/config-plugins.md cobre a superfície da API para autores de módulos.

Mudanças nativas compostas que sobrevivem ao expo prebuild --clean (o padrão do SDK 57). Plugins de configuração codificam permissões, entitlements, dependências Gradle e entradas de manifesto em TypeScript versionado - não em cliques manuais no Xcode.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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 =
      "Permitir que $(PRODUCT_NAME) use Meu Recurso.";
    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: "MeuApp",
  slug: "meu-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 execução: git diff ios android deve estar vazio

Quando usar isso:

Adicionando descrições de uso do iOS ou permissões do Android
Conectando chaves de SDK de terceiros em Info.plist / AndroidManifest.xml
Ajustando minSdkVersion do Gradle, target de implantação do iOS ou regras do ProGuard
Portando edições nativas de brownfield para CNG reproduzível

Exemplo de Trabalho

Uma pilha de plugins compostos para um aplicativo que precisa de acesso à câmera, um esquema de URL personalizado e um target de implantação compartilhado - configuração típica de produção do 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: "Loja",
  slug: "loja",
  scheme: "loja",
  ios: {
    bundleIdentifier: "com.example.loja",
  },
  android: {
    package: "com.example.loja",
  },
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission: "Escanear códigos de barras de produtos na loja.",
      },
    ],
    [withAppLinks, { domain: "loja.example.com" }],
    [
      "expo-build-properties",
      {
        ios: { deploymentTarget: "15.1" },
        android: { minSdkVersion: 24 },
      },
    ],
  ],
};
 
export default config;

# Valida a saída do plugin sem compilação completa
npx expo config --type introspect
 
# Gera e verifica a idempotência
rm -rf ios android
npx expo prebuild --no-install
npx expo prebuild --no-install

O que isso demonstra:

Plugin de biblioteca primeiro - expo-camera gerencia as strings de permissão da câmera
Plugin personalizado parametrizado - withAppLinks aceita domain e deduplica entitlements
Build properties por último - expo-build-properties ajusta as versões da toolchain após os plugins de recursos
Idempotência - o domínio associado é anexado apenas se estiver ausente

Mergulho Profundo

Como Funcionam os Plugins de Configuração

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

Avaliação: O Expo carrega app.config.ts e resolve o array plugins (strings, tuplas ou funções).
Pipeline de mods: Cada plugin recebe ExpoConfig e retorna a configuração modificada através de helpers with* (withInfoPlist, withGradleProperties, etc.).
Merge de template: Arquivos de template do SDK 57 são copiados, e então os mods são aplicados na ordem dos plugins.
Regeneração limpa: O prebuild padrão exclui as pastas primeiro - apenas as alterações codificadas nos plugins persistem.

Padrões de Composição

Padrão	Use Quando
Plugin de string `"expo-router"`	A biblioteca envia um plugin zero-config
Tupla `["expo-camera", { ... }]`	O plugin da biblioteca precisa de opções
Função `withMyFeature`	Mutação nativa personalizada
Tupla + função `[withAppLinks, { domain }]`	Plugin personalizado com parâmetros
`withPlugins(config, [a, b, c])`	Agrupar mods relacionados em um único arquivo

// plugins/index.ts - compõe 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: "loja.example.com" }],
    [withPushEnvironment, { env: "production" }],
  ]);
 
export default withNativeStack;

Regras de Ordem de Plugins

Plugins que criam a estrutura base rodam antes dos plugins que corrigem o mesmo arquivo
Entitlements antes dos recursos que dependem deles
expo-build-properties geralmente roda tarde - o target de implantação afeta outros pods
Ao depurar, divida o array plugins - remova metade até que o prebuild seja bem-sucedido

Checklist de Idempotência

Anti-padrão	Correção
Anexar o mesmo XML a cada execução	Verifique se o nó existe antes de `add`
Duplicar chaves `NSCameraUsageDescription`	Mesclar na chave existente ou usar plugin de biblioteca
Substituição de Regex sem âncora	Use mods estruturados (`withInfoPlist`) em vez de arquivos de texto
`apply plugin` global do Gradle duas vezes	Proteja com `if (!contents.includes(...))`

Depuração

# Veja os mods resolvidos sem escrever ios/android
npx expo config --type introspect
 
# Diff após alteração do plugin
rm -rf ios android && npx expo prebuild --no-install
git diff ios   # se rastreado; equipes CNG inspecionam no IDE
 
# Doctor pega configuração de plugin inválida
npx expo-doctor

Armadilhas

Editar ios/ após o prebuild - O padrão clean do SDK 57 apaga as alterações. Correção: Codifique em um plugin.
Ordem incorreta de plugins - O plugin posterior sobrescreve a chave Info.plist anterior. Correção: Documente a ordem; use introspect.
Anexação não-idempotente - O segundo prebuild duplica entradas do manifesto. Correção: Verificação de existência antes de adicionar.
npm install para pacotes de plugin - Desvio de versão em relação aos binários nativos do SDK 57. Correção: npx expo install.
Testando apenas no Expo Go - Plugins que afetam entitlements precisam de reconstrução do cliente de desenvolvimento. Correção: expo run:ios após a aplicação dos plugins.
Importando do caminho errado - Use expo/config-plugins em plugins de app; bibliotecas usam @expo/config-plugins conforme a documentação do pacote.

Alternativas

Alternativa	Use Quando	Não Use Quando
Plugin de configuração (recomendado)	Qualquer alteração nativa repetível sob CNG	Experimento local único sem caminho de produção
Plugin embutido da biblioteca	O pacote documenta a entrada `plugins`	A biblioteca não tem plugin SDK 57 - fork ou ADR
`expo-build-properties`	Versões do SDK, ProGuard, target de implantação	XML de manifesto complexo - escreva um plugin personalizado
Pastas nativas commitadas (brownfield)	Aplicativo legado sem caminho de migração de plugin	Aplicativos Greenfield SDK 57 - use CNG
`patch-package` em arquivos gerados	Hotfix de emergência com ADR	Fluxo de trabalho padrão - patches perdidos em prebuild limpo

FAQs

Onde os plugins de configuração são executados?

No tempo de prebuild na máquina que executa expo prebuild ou EAS Build - não a cada recarga do Metro. Reconstrua os binários nativos após alterações de plugin que afetam entitlements ou dependências nativas.

Posso usar plugins de configuração sem commitar ios/?

Sim - esse é o padrão CNG. Plugins são a fonte da verdade; pastas nativas são saídas efêmeras.

Como testo um plugin sem uma compilação completa?

npx expo config --type introspect mostra os resultados dos mods. Para validação final, execute o prebuild duas vezes e confirme zero diff.

Qual a diferença entre os plugins de app.config e a página de config-plugins de native-modules?

Esta página foca no fluxo de trabalho CNG - composição, idempotência e sobrevivência ao prebuild. ../native-modules/config-plugins/config-plugins.md cobre a superfície da API para autores de módulos.

Relacionados

Noções Básicas de Prebuild - o que o prebuild gera
Fluxo de Trabalho do expo prebuild - checklist de regeneração limpa e iteração local
../native-modules/config-plugins/config-plugins.md - API de plugin para autores de módulos nativos
../native-modules/patching-native-projects/patching-native-projects.md - quando patches são inevitáveis
../expo-rules/native-module-rules/native-module-rules.md - Regras de instalação e plugin de Nível 2
Código Nativo Personalizado no CNG - expo run:ios/android após a aplicação dos plugins

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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 =
      "Permitir que $(PRODUCT_NAME) use Meu Recurso.";
    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: "MeuApp",
  slug: "meu-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 execução: git diff ios android deve estar vazio

Quando usar isso:

Adicionando descrições de uso do iOS ou permissões do Android
Conectando chaves de SDK de terceiros em Info.plist / AndroidManifest.xml
Ajustando minSdkVersion do Gradle, target de implantação do iOS ou regras do ProGuard
Portando edições nativas de brownfield para CNG reproduzível

Exemplo de Trabalho

// 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: "Loja",
  slug: "loja",
  scheme: "loja",
  ios: {
    bundleIdentifier: "com.example.loja",
  },
  android: {
    package: "com.example.loja",
  },
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission: "Escanear códigos de barras de produtos na loja.",
      },
    ],
    [withAppLinks, { domain: "loja.example.com" }],
    [
      "expo-build-properties",
      {
        ios: { deploymentTarget: "15.1" },
        android: { minSdkVersion: 24 },
      },
    ],
  ],
};
 
export default config;

# Valida a saída do plugin sem compilação completa
npx expo config --type introspect
 
# Gera e verifica a idempotência
rm -rf ios android
npx expo prebuild --no-install
npx expo prebuild --no-install

O que isso demonstra:

Plugin de biblioteca primeiro - expo-camera gerencia as strings de permissão da câmera
Plugin personalizado parametrizado - withAppLinks aceita domain e deduplica entitlements
Build properties por último - expo-build-properties ajusta as versões da toolchain após os plugins de recursos
Idempotência - o domínio associado é anexado apenas se estiver ausente

Mergulho Profundo

Como Funcionam os Plugins de Configuração

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

Avaliação: O Expo carrega app.config.ts e resolve o array plugins (strings, tuplas ou funções).
Pipeline de mods: Cada plugin recebe ExpoConfig e retorna a configuração modificada através de helpers with* (withInfoPlist, withGradleProperties, etc.).
Merge de template: Arquivos de template do SDK 57 são copiados, e então os mods são aplicados na ordem dos plugins.
Regeneração limpa: O prebuild padrão exclui as pastas primeiro - apenas as alterações codificadas nos plugins persistem.

Padrões de Composição

Padrão	Use Quando
Plugin de string `"expo-router"`	A biblioteca envia um plugin zero-config
Tupla `["expo-camera", { ... }]`	O plugin da biblioteca precisa de opções
Função `withMyFeature`	Mutação nativa personalizada
Tupla + função `[withAppLinks, { domain }]`	Plugin personalizado com parâmetros
`withPlugins(config, [a, b, c])`	Agrupar mods relacionados em um único arquivo

// plugins/index.ts - compõe 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: "loja.example.com" }],
    [withPushEnvironment, { env: "production" }],
  ]);
 
export default withNativeStack;

Regras de Ordem de Plugins

Plugins que criam a estrutura base rodam antes dos plugins que corrigem o mesmo arquivo
Entitlements antes dos recursos que dependem deles
expo-build-properties geralmente roda tarde - o target de implantação afeta outros pods
Ao depurar, divida o array plugins - remova metade até que o prebuild seja bem-sucedido

Checklist de Idempotência

Anti-padrão	Correção
Anexar o mesmo XML a cada execução	Verifique se o nó existe antes de `add`
Duplicar chaves `NSCameraUsageDescription`	Mesclar na chave existente ou usar plugin de biblioteca
Substituição de Regex sem âncora	Use mods estruturados (`withInfoPlist`) em vez de arquivos de texto
`apply plugin` global do Gradle duas vezes	Proteja com `if (!contents.includes(...))`

Depuração

# Veja os mods resolvidos sem escrever ios/android
npx expo config --type introspect
 
# Diff após alteração do plugin
rm -rf ios android && npx expo prebuild --no-install
git diff ios   # se rastreado; equipes CNG inspecionam no IDE
 
# Doctor pega configuração de plugin inválida
npx expo-doctor

Armadilhas

Editar ios/ após o prebuild - O padrão clean do SDK 57 apaga as alterações. Correção: Codifique em um plugin.
Ordem incorreta de plugins - O plugin posterior sobrescreve a chave Info.plist anterior. Correção: Documente a ordem; use introspect.
Anexação não-idempotente - O segundo prebuild duplica entradas do manifesto. Correção: Verificação de existência antes de adicionar.
npm install para pacotes de plugin - Desvio de versão em relação aos binários nativos do SDK 57. Correção: npx expo install.
Testando apenas no Expo Go - Plugins que afetam entitlements precisam de reconstrução do cliente de desenvolvimento. Correção: expo run:ios após a aplicação dos plugins.
Importando do caminho errado - Use expo/config-plugins em plugins de app; bibliotecas usam @expo/config-plugins conforme a documentação do pacote.

Alternativas

Alternativa	Use Quando	Não Use Quando
Plugin de configuração (recomendado)	Qualquer alteração nativa repetível sob CNG	Experimento local único sem caminho de produção
Plugin embutido da biblioteca	O pacote documenta a entrada `plugins`	A biblioteca não tem plugin SDK 57 - fork ou ADR
`expo-build-properties`	Versões do SDK, ProGuard, target de implantação	XML de manifesto complexo - escreva um plugin personalizado
Pastas nativas commitadas (brownfield)	Aplicativo legado sem caminho de migração de plugin	Aplicativos Greenfield SDK 57 - use CNG
`patch-package` em arquivos gerados	Hotfix de emergência com ADR	Fluxo de trabalho padrão - patches perdidos em prebuild limpo

FAQs

Onde os plugins de configuração são executados?

Posso usar plugins de configuração sem commitar ios/?

Sim - esse é o padrão CNG. Plugins são a fonte da verdade; pastas nativas são saídas efêmeras.

Como testo um plugin sem uma compilação completa?

npx expo config --type introspect mostra os resultados dos mods. Para validação final, execute o prebuild duas vezes e confirme zero diff.

Qual a diferença entre os plugins de app.config e a página de config-plugins de native-modules?

Relacionados

Noções Básicas de Prebuild - o que o prebuild gera
Fluxo de Trabalho do expo prebuild - checklist de regeneração limpa e iteração local
../native-modules/config-plugins/config-plugins.md - API de plugin para autores de módulos nativos
../native-modules/patching-native-projects/patching-native-projects.md - quando patches são inevitáveis
../expo-rules/native-module-rules/native-module-rules.md - Regras de instalação e plugin de Nível 2
Código Nativo Personalizado no CNG - expo run:ios/android após a aplicação dos plugins

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Plugins de Configuração no CNG

Buscar na documentação

Plugins de Configuração no CNG