Config plugins e prebuild no Expo

Expo Prebuild lê a configuração do app e gera projetos Android e iOS. Config plugins são funções que modificam essa configuração nativa durante a geração. Você declara a intenção em app.json ou app.config.ts, executa o prebuild e evita transformar arquivos gerados em uma segunda fonte de verdade.

Essa etapa aparece quando uma development build precisa de permissões, módulos ou valores nativos próprios. Ela não é necessária para cada alteração de JavaScript.

No guia de Expo, app config e Prebuild ficam entre o código React Native e o binário instalado. Essa posição orienta o diagnóstico: se JSX mudou, o Metro basta; se uma propriedade do Info.plist ou AndroidManifest.xml mudou, o projeto nativo precisa ser regenerado e compilado.

A planta que a máquina transforma em obra

Pense numa planta arquitetônica. Ela registra portas, instalações e medidas. A máquina de construção lê a planta e ergue uma versão da obra; se você derrubar e reconstruir, alterações feitas diretamente numa parede podem desaparecer.

No mapa técnico, a app config é a planta, o config plugin é uma regra que acrescenta instruções e o Prebuild é a geração de android/ e ios/. Esse fluxo recebe o nome de Continuous Native Generation, ou CNG.

O limite da analogia é que os projetos gerados são código real e podem ser abertos no Android Studio ou Xcode. Ainda assim, se a equipe escolheu CNG, a fonte durável fica na configuração e nos plugins. Tecnicamente, rodar prebuild limpo recalcula o resultado; edições manuais não representadas podem ser apagadas.

Veja a configuração resolvida, não apenas o arquivo

Um app.json básico contém o objeto expo:

{
  "expo": {
    "name": "Passo a Passo",
    "slug": "passo-a-passo",
    "version": "1.0.0",
    "orientation": "portrait",
    "ios": { "bundleIdentifier": "com.exemplo.passoapasso" },
    "android": { "package": "com.exemplo.passoapasso" }
  }
}

O nome e slug identificam o projeto em contextos diferentes; bundleIdentifier e package identificam os aplicativos nas plataformas. Escolha esses ids com cuidado: lojas e credenciais passam a depender deles.

Exiba a configuração final que o Expo realmente lê:

npx expo config --type public

Configuração dinâmica, variáveis e plugins podem mudar o resultado. O comando é mais confiável que olhar apenas um trecho do arquivo e supor que nada o transformou. Não exponha segredos: tudo que entra na configuração pública ou no bundle deve ser tratado como visível ao usuário.

Instale plugins fornecidos pelas bibliotecas

Muitos módulos Expo incluem seu próprio plugin. A entrada recebe o nome do pacote e, quando suportado, opções:

{
  "expo": {
    "plugins": [
      [
        "expo-camera",
        {
          "cameraPermission": "Permita que o app fotografe seu comprovante."
        }
      ]
    ]
  }
}

Não invente uma opção pelo nome. Cada plugin define seu schema e as plataformas afetadas. Instale o módulo com npx expo install, confira a documentação da versão do SDK e só depois inclua configuração adicional.

Escreva um plugin mínimo e verificável

Para enxergar o mecanismo sem pedir câmera, crie plugins/with-environment.js. O plugin adiciona uma chave ao Info.plist do iOS:

const { withInfoPlist } = require('expo/config-plugins');

module.exports = function withEnvironment(config, props = {}) {
  const environment = props.environment ?? 'development';

  return withInfoPlist(config, (modConfig) => {
    modConfig.modResults.PassoEnvironment = environment;
    return modConfig;
  });
};

withInfoPlist é um mod, uma função que recebe o resultado intermediário de um arquivo nativo, modifica modResults e devolve a configuração. Manter o plugin determinístico é essencial: a mesma entrada deve gerar o mesmo resultado sem duplicar linhas a cada execução.

Registre o caminho e uma propriedade no app.json:

{
  "expo": {
    "plugins": [
      ["./plugins/with-environment", { "environment": "preview" }]
    ]
  }
}

Um plugin local pode ficar em JavaScript para ser carregado diretamente pelo Node. Se usar TypeScript ou uma biblioteca publicada, siga o fluxo de build recomendado pela documentação de plugins.

Inspecione o plugin antes de gerar tudo

O comando abaixo resolve plugins e mostra rastros úteis:

EXPO_DEBUG=1 npx expo prebuild --platform ios --no-install

--no-install evita instalar dependências nativas depois da geração; isso foi suficiente para a prova editorial. No macOS usado, a saída terminou com:

Depois da execução, a chave apareceu em ios/PassoaPasso/Info.plist:

<key>PassoEnvironment</key>
<string>preview</string>

Essa é a volta ao comportamento técnico: a função JavaScript não roda quando a pessoa abre a tela. Ela roda durante prebuild e materializa uma propriedade no projeto iOS que será compilado no binário.

Gere com clean sabendo exatamente o que será recriado

Quando quer provar que a app config consegue reconstruir a plataforma, use:

npx expo prebuild --clean

--clean remove e recria os diretórios nativos. É a conferência mais segura contra resíduos de uma geração anterior, mas também torna explícito o risco: uma edição manual dentro de android/ ou ios/ pode sumir. Faça commit antes, revise o diff e mantenha ajustes duráveis em config plugins.

No SDK 57, o comportamento de regeneração foi endurecido, mas escrever --clean continua comunicando a intenção para quem lê o comando e acompanha o diff.

Reproduza um plugin que não pode ser resolvido

Se o caminho no app.json estiver errado:

{
  "expo": {
    "plugins": ["./plugins/with-enviroment"]
  }
}

o prebuild para antes de gerar uma configuração confiável. A mensagem central é desta família:

Compare o nome real with-environment.js, corrija a grafia e rode npx expo config antes de repetir o prebuild. Não crie um arquivo vazio com o nome errado: isso esconderia a causa e deixaria a modificação necessária sem efeito.

Saiba quando um rebuild é obrigatório

Use esta tabela de bolso:

Mudança                         Prebuild?   Nova build nativa?
Texto ou lógica React             não             não
Pacote só JavaScript              não             não
Plugin ou permissão nativa        sim             sim
Ícone, splash ou identificador    sim             sim
Valor entregue por EAS Update     não*            não*

Os asteriscos dependem de o valor estar no bundle e ser compatível com o mesmo runtime. Alteração que muda código ou configuração nativa não cabe em update de JavaScript; esse limite será retomado na lição de EAS.

Missão: prove idempotência

Crie um plugin que adicione uma descrição nativa, execute prebuild limpo duas vezes e compare os resultados. A chave deve aparecer uma única vez e com o mesmo valor.

npx expo prebuild --clean --platform ios --no-install
cp ios/PassoaPasso/Info.plist /tmp/info-primeira.plist
npx expo prebuild --clean --platform ios --no-install
diff /tmp/info-primeira.plist ios/PassoaPasso/Info.plist

Adapte o nome do diretório iOS ao seu projeto e não use /tmp para guardar o único exemplar de algo importante. Se diff não imprimir diferenças, a geração é reproduzível para essa entrada. Depois conecte a configuração a EAS Build, Update e Submit.