Ambientes e build profiles no app: como separar dev, preview e producao sem confusao

Muito app corporativo mobile comeca com uma variavel improvisada, um endpoint trocado na mao e uma equipe que jura lembrar qual build aponta para homologacao. Funciona por alguns dias. Depois comeca o caos: development build falando com producao, preview build saindo com nome errado, endpoint publico levando dado de teste para release real e segredo indo parar no bundle porque alguem confundiu variavel publica com credencial privada.

Esse problema nao nasce por falta de ferramenta. Ele nasce porque ambiente, build profile, app config e segredo real costumam ser tratados como a mesma coisa. Em React Native com Expo e EAS, essa confusao custa caro: teste ruim, release errado, suporte sem contexto e retrabalho em cima de uma configuracao que deveria ser previsivel.

Este guia organiza uma abordagem pratica para separar development, preview e production em apps corporativos: uso correto de EXPO_PUBLIC_, limites de .env, papel do app.config, leitura por Constants.expoConfig, configuracao de eas.json com extends e criterio para decidir o que e publico, o que e interno e o que nunca deve entrar no app.

1. Ambiente nao e a mesma coisa que build profile

Antes de mexer em arquivo, vale separar conceitos que muita equipe mistura:

• ambiente: contexto de uso, como development, homologacao, preview ou producao;
• build profile: conjunto de instrucoes de build usado para gerar um binario especifico;
• app config: configuracao do app Expo, com nome, icone, scheme, extras e variacoes por ambiente;
• variavel publica: valor que pode aparecer no bundle do app;
• segredo real: valor que nao deve ser embutido no aplicativo.

Essa separacao evita o erro classico de usar o mesmo pacote de configuracao para tudo. Build profile ajuda a definir como o binario nasce. Ambiente ajuda a decidir para onde ele aponta. Segredo real, por sua vez, normalmente pertence ao backend, ao provedor ou ao builder, e nao ao bundle entregue ao usuario.

2. O que o Expo faz com EXPO_PUBLIC_

A documentacao oficial do Expo sobre environment variables explica que a Expo CLI carrega automaticamente variaveis com prefixo EXPO_PUBLIC_ a partir de arquivos .env para uso no JavaScript do app. A mesma documentacao tambem deixa um aviso fundamental: esses valores ficam visiveis em texto claro no aplicativo compilado.

Em outras palavras, EXPO_PUBLIC_ serve para configuracao publica de cliente, nao para segredo real.

Exemplos aceitaveis:

• URL publica da API;
• nome amigavel do ambiente;
• flag visual de build preview;
• chave publica de servico que ja e publica por natureza.

Exemplos que nao deveriam ir para esse espaco:

• senha de banco;
• token administrativo;
• segredo de provedor;
• credencial privada do backend;
• qualquer dado que exponha capacidade privilegiada fora do aparelho.

Se o app final pode ser inspecionado pelo usuario, nao faz sentido esconder segredo critico dentro dele.

3. .env ajuda, mas nao governa tudo sozinho

A mesma documentacao do Expo mostra que a CLI segue a resolucao padrao de arquivos .env e que voce pode usar combinacoes como .env e .env.local. Ela tambem recomenda manter variantes locais fora do Git quando representam configuracao especifica da maquina.

Isso e util, mas nao resolve toda a modelagem de ambiente. Um projeto maduro costuma tratar .env como apoio para desenvolvimento local e para injetar variaveis publicas na bundle, e nao como unico orquestrador de release.

Um desenho simples para time pequeno:

• .env com defaults seguros do projeto;
• .env.local fora do Git para ajustes da maquina local;
• variaveis do builder ou CI para build remoto;
• profiles em eas.json para diferenciar development, preview e production.

Esse modelo reduz a chance de um build depender de um arquivo local que so existe na maquina de uma pessoa.

4. Nao use NODE_ENV como volante de todos os ambientes

A documentacao oficial do Expo recomenda evitar o uso de NODE_ENV para alternar arquivos .env de forma operacional. Ela explica que alguns comandos do ecossistema forcam NODE_ENV=production, como export e update, o que pode gerar surpresa se a equipe tentar dirigir tudo apenas por esse caminho.

Traducao pratica: usar NODE_ENV como chave universal para decidir qual API, qual bundle e qual update deve sair costuma ser mais fragil do que parece.

Melhor separar:

• variavel explicita para o ambiente do app;
• build profiles claros em eas.json;
• scripts ou automacao para carregar o conjunto certo de variaveis.

Isso fica ainda mais importante em projetos Windows, CI e update OTA, onde o comportamento implicito pode confundir bastante.

5. O que um build profile deve carregar

A documentacao do eas.json mostra que voce pode definir perfis de build em build, usar extends para reaproveitar configuracao e informar env por profile. Ela tambem mostra exemplos com perfis como development, staging e production, alem de casos com distribuicao interna.

Em app corporativo, um build profile saudavel costuma responder a perguntas como:

• esse binario e para dev local, preview interno ou release final?
• ele aponta para qual API?
• ele usa distribuicao interna ou loja?
• precisa development client?
• qual nome e identidade visual deixam claro o ambiente?

Build profile nao deveria ser apenas um apelido. Ele deveria reduzir o risco humano de publicar o binario errado.

6. Um modelo simples de development, preview e production

O conjunto mais facil de manter para muitos times pequenos e este:

• development: usado pelo time para testar recursos nativos reais, com development build e endpoint de desenvolvimento ou homologacao controlada;
• preview: build interna para validador, com distribuicao interna e configuracao mais proxima da experiencia final;
• production: build que vai para loja e fala com a API de producao.

A documentacao do eas.json mostra precisamente esse tipo de composicao, inclusive com distribution: internal e env por profile. Em vez de criar dez variacoes cedo demais, normalmente vale comecar com tres perfis bem definidos.

7. extends evita duplicacao e divergencia

Outro detalhe util do eas.json e o uso de extends. A documentacao mostra exemplos em que um profile base concentra configuracao comum e os demais especializam apenas o que muda.

Isso vale muito quando o app compartilha a maior parte da configuracao, mas muda alguns pontos entre preview e production. Sem extends, o projeto duplica configuracao e comeca a divergir em silencio. Um profile recebe variavel nova, o outro nao. Um nome e atualizado, outro fica velho. Uma mudanca de distribuicao entra em um lado e some no outro.

Com uma base comum, a equipe deixa explicito o que e padrao e o que e excecao.

8. app.config e onde o app muda de identidade com criterio

A documentacao de configuracao do Expo explica que o app config governa nome, icone, splash, scheme, chaves publicas e outros metadados do aplicativo. Ela tambem explica que configuracoes dinamicas em app.config.js ou app.config.ts podem reagir a variaveis de ambiente.

Isso abre um caminho importante: em vez de trocar nome e scheme manualmente antes de cada build, o projeto pode derivar essa identidade do ambiente de forma previsivel.

Exemplos do que pode variar por ambiente:

• nome visivel do app, como incluir Preview ou Dev;
• scheme e deep link quando a estrategia pedir;
• extras publicos usados no runtime;
• IDs ou chaves publicas especificas de ambiente;
• liga ou desliga de recursos visiveis de teste.

Essa estrategia conversa bem com os artigos de deep links, feature flags e compatibilidade entre app e API.

9. Constants.expoConfig e extra ajudam a ler configuracao em runtime

A documentacao de configuracao do Expo tambem diz que a maior parte do app config fica acessivel em runtime por meio de Constants.expoConfig. Ela mostra ainda que a chave extra pode carregar dados arbitrarios para o app.

Isso e util quando a equipe precisa ler informacoes publicas do ambiente em execucao, como:

• nome logico do ambiente;
• endpoints publicos;
• identificador de canal;
• comportamento visual de preview.

Mas a mesma documentacao traz o limite importante: voce nao deve colocar informacao sensivel no app config publico. Se o app consegue ler em runtime, o usuario final tambem pode descobrir de alguma forma.

10. npx expo config --type public e um teste simples que evita erro caro

A documentacao do Expo recomenda usar npx expo config --type public para verificar o que realmente sera embutido nas builds e updates e ficara disponivel em runtime. Esse comando deveria entrar no checklist do time sempre que houver duvida sobre o que esta saindo no app.

Ele ajuda a responder perguntas criticas:

• esse valor esta publico sem eu perceber?
• o nome do app ficou certo para preview?
• o extra esta trazendo o endpoint certo?
• o build esta refletindo o ambiente esperado?

Muito erro de configuracao passa despercebido porque a equipe confia no arquivo e nao valida o resultado publico final.

11. Como pensar segredo de verdade em app mobile

O erro mais caro aqui costuma ser conceitual: tentar resolver segredo do backend dentro do app. Em app mobile, quase todo segredo critico deveria viver fora do bundle, normalmente no backend, no provedor ou em infraestrutura controlada.

Algumas regras praticas ajudam:

• se o app precisa chamar a API, ele pode conhecer a URL publica dela;
• se o backend precisa falar com servico privilegiado, o segredo deve ficar no backend;
• se o builder precisa de credencial para gerar release, isso pertence ao ambiente de build, nao ao JavaScript do app;
• se um valor nao pode cair na mao do usuario final, ele nao deveria morar em EXPO_PUBLIC_ nem em Constants.expoConfig.

Essa separacao conversa diretamente com o artigo segredos e variaveis de ambiente e ajuda a evitar a falsa sensacao de seguranca que nasce quando um segredo esta apenas escondido em um app compilado.

12. Preview build nao deve ser producao disfarcada

Muitas equipes dizem que possuem preview, mas na pratica entregam um binario quase identico ao de producao, inclusive com endpoint real, analytics real e comportamento que confunde validacao com operacao. Esse e um problema de governanca, nao de sintaxe.

Um preview build util costuma ter:

• nome visivel que o diferencia do app final;
• distribuicao interna;
• API de homologacao ou ambiente controlado;
• telemetria que permita separar teste de uso real;
• fluxo de autenticacao compativel com validador;
• recursos nativos e navegacao equivalentes aos da release.

Assim o preview cumpre o papel de validar a experiencia real sem misturar teste interno com a base de producao.

13. Expo Go, development build e preview build resolvem fases diferentes

O ecossistema Expo oferece mais de uma forma de testar o aplicativo, mas elas nao servem ao mesmo momento:

• Expo Go: bom para experimentar tela e navegacao no inicio, desde que o projeto caiba nos modulos embutidos;
• development build: necessario quando a equipe precisa validar recursos nativos reais e comportamento mais proximo do app final;
• preview build: binario interno para teste de fluxo, validacao de negocio e aceitacao antes da loja.

Quando essas fases se misturam, o time aprova no ambiente errado e descobre o problema tarde. O artigo Expo, development build e EAS Build continua sendo a base para essa conversa. Este guia entra para aprofundar a parte de ambientes e configuracao.

14. A API precisa respeitar o desenho de ambiente do app

Separar build profile sem separar contrato e endpoint da API produz uma meia-solucao. O app precisa saber para qual backend aponta e o backend precisa aceitar essa estrategia sem ambiguidades.

Checklist minimo:

• endpoint explicito por ambiente;
• telemetria com sinal claro de origem;
• dados de homologacao isolados dos dados reais;
• politica de login e contas de teste compativeis com preview;
• cuidado para que o app antigo nao aponte sem querer para API errada.

Esse ponto se conecta ao checklist de API REST e aos artigos de compatibilidade e atualizacao obrigatoria.

15. Erros comuns

• guardar segredo real em EXPO_PUBLIC_;
• usar NODE_ENV como volante unico de todos os ambientes;
• duplicar perfis em eas.json sem extends;
• fazer preview apontar para producao sem aviso claro;
• trocar nome e scheme manualmente antes de cada build;
• nao validar o resultado com npx expo config --type public;
• confundir Expo Go com validacao real de recurso nativo;
• deixar o ambiente depender de um arquivo local que so existe em uma maquina.

16. Um roteiro pratico para organizar isso no app corporativo

1. Definir tres perfis claros: development, preview e production.
2. Criar um profile base em eas.json e usar extends.
3. Separar variaveis publicas de segredo real.
4. Usar app.config para nome, identidade e extras publicos por ambiente.
5. Revisar o que o app le em runtime por Constants.expoConfig.
6. Testar o resultado publico com npx expo config --type public.
7. Garantir que preview e producao apontam para APIs corretas.
8. Documentar o fluxo de build para que ele nao dependa da memoria de uma pessoa.

17. Quando vale um diagnostico tecnico

Se cada build do app gera duvida sobre endpoint, ambiente, segredo, identidade do binario ou caminho de release, provavelmente o problema nao e apenas um arquivo de configuracao. Falta um modelo de operacao entre app, backend, CI e produto. Nessa hora, um diagnostico tecnico ajuda a organizar o desenho antes que cada nova release carregue risco operacional desnecessario.

Ambiente maduro em app mobile nao e o que tem mais arquivos. E o que deixa claro o que e publico, o que e segredo, para onde cada build aponta e como o time repete isso sem improviso.

Referencias editoriais: Expo - Environment variables, Expo - Configure EAS Build with eas.json e Expo - Configure with app config.