app.json & app.config.js

Q: Qual é a diferença entre app.json e app.config.js?

app.json é JSON estático que as ferramentas podem atualizar automaticamente. app.config.js / app.config.ts é dinâmico - suporta variáveis, ramificação de ambiente e TypeScript. O Expo mescla o estático no dinâmico quando você exporta uma função.

Q: Qual arquivo deve conter minha configuração?

Mantenha um app.json mínimo se as ferramentas o esperarem, mas prefira app.config.ts como a fonte da verdade para qualquer coisa dependente do ambiente. Execute npx expo config para ver o resultado mesclado.

Q: Como leio valores de configuração dentro do meu aplicativo React Native?

Use expo-constants: Para variáveis EXPO_PUBLIC_, use process.env.EXPO_PUBLIC_API_URL diretamente nos arquivos de origem.

Q: Como funcionam as variáveis de ambiente EXPO_PUBLIC_?

O Expo CLI carrega arquivos .env e incorpora referências process.env.EXPO_PUBLIC_* ao seu bundle JavaScript no momento do build. Eles são visíveis para os usuários finais - nunca armazene segredos lá.

Q: Para que serve o campo extra?

extra é um objeto JSON arbitrário copiado para o manifesto público. Passe flags de recursos, rótulos de ambiente ou endpoints não sensíveis. Leia-o via Constants.expoConfig.extra.

Q: Como configuro diferentes IDs de bundle por ambiente?

Ramifique em app.config.ts com base em APP_ENV: Defina APP_ENV ao executar eas build ou localmente no seu shell.

Q: Armadilha: Por que minha variável EXPO_PUBLIC_ apareceu como undefined?

Causas comuns: prefixo EXPO_PUBLIC_ ausente, uso de notação de colchetes (process.env['EXPO_PUBLIC_X']), ou esquecer de reiniciar o Metro após alterar .env. Corrija o prefixo, use notação de ponto e execute npx expo start --clear.

Configure como o Expo pré-compila projetos nativos, como seu aplicativo carrega no Expo Go e em builds de desenvolvimento, e quais valores não secretos chegam ao JavaScript em tempo de execução - sem vazar credenciais para o bundle.

Receita

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

// app.config.ts
import { ExpoConfig, ConfigContext } from "expo/config";
 
const APP_ENV = process.env.APP_ENV ?? "development";
 
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: APP_ENV === "production" ? "Acme" : "Acme (Dev)",
  slug: "acme-mobile",
  scheme: "acme",
  extra: {
    appEnv: APP_ENV,
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "https://staging.api.acme.test",
  },
  ios: { bundleIdentifier: "com.acme.mobile" },
  android: { package: "com.acme.mobile" },
});

# Inspecione o manifesto público resolvido (o que Constants.expoConfig exporá)
APP_ENV=development EXPO_PUBLIC_API_URL=https://staging.api.acme.test npx expo config --type public

Quando usar isso:

Definir identificadores de bundle, ícones, splash screen, scheme de deep-link e configurações do EAS Update.
Ramificar o nome do aplicativo, URLs de API ou flags de recursos por ambiente sem manter três repositórios.
Passar valores não secretos de tempo de execução para JS via extra e Constants.expoConfig.
Registrar plugins de configuração que modificam android/ e ios/ durante o prebuild.

Exemplo de Trabalho

// app.config.ts - staging vs production com padrões seguros contra segredos
import { ExpoConfig, ConfigContext } from "expo/config";
 
type AppEnv = "development" | "staging" | "production";
 
function resolveEnv(): AppEnv {
  const raw = process.env.APP_ENV ?? "development";
  if (raw === "staging" || raw === "production") return raw;
  return "development";
}
 
const env = resolveEnv();
 
const apiUrlByEnv: Record<AppEnv, string> = {
  development: "http://localhost:4000",
  staging: "https://staging.api.acme.test",
  production: "https://api.acme.com",
};
 
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: env === "production" ? "Acme" : `Acme (${env})`,
  slug: "acme-mobile",
  scheme: "acme",
  version: "1.4.0",
  orientation: "portrait",
  userInterfaceStyle: "automatic",
  plugins: ["expo-router"],
  extra: {
    appEnv: env,
    // Apenas valores não secretos - legíveis no aplicativo compilado
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? apiUrlByEnv[env],
    featureFlags: {
      newCheckout: env !== "production",
    },
  },
  ios: {
    bundleIdentifier:
      env === "production" ? "com.acme.mobile" : `com.acme.mobile.${env}`,
    supportsTablet: true,
  },
  android: {
    package: env === "production" ? "com.acme.mobile" : `com.acme.mobile.${env}`,
    adaptiveIcon: {
      foregroundImage: "./assets/adaptive-icon.png",
      backgroundColor: "#ffffff",
    },
  },
});

// src/config/runtime.ts - leia a configuração resolvida em tempo de execução (não app.config.ts bruto)
import Constants from "expo-constants";
 
type Extra = {
  appEnv: "development" | "staging" | "production";
  apiUrl: string;
  featureFlags: { newCheckout: boolean };
};
 
const extra = Constants.expoConfig?.extra as Extra;
 
export const appEnv = extra.appEnv;
export const apiUrl = extra.apiUrl;
export const featureFlags = extra.featureFlags;

# Desenvolvimento local (API de staging)
APP_ENV=staging EXPO_PUBLIC_API_URL=https://staging.api.acme.test npx expo start
 
# Build de produção EAS - segredos vivem no EAS, não em app.config
APP_ENV=production eas build --profile production --platform ios

O que isso demonstra:

app.config.ts mescla valores estáticos de app.json usando o padrão de middleware ({ config }).
APP_ENV alterna identificadores nativos e nome de exibição por ambiente.
Variáveis EXPO_PUBLIC_* são incorporadas ao JS no momento do bundle; extra expõe a configuração via Constants.expoConfig.
npx expo config --type public pré-visualiza o manifesto visível para o cliente antes do envio.

Mergulho Profundo

Como Funciona

O Expo CLI procura por configuração estática (app.json ou app.config.json) e configuração dinâmica (app.config.js / app.config.ts). Se ambos existirem, o dinâmico prevalece após a mesclagem.
Se a configuração dinâmica exportar uma função, o Expo passa a configuração estática normalizada como { config } e usa o valor de retorno como o manifesto final.
A configuração resolvida é serializada para JSON antes que qualquer ferramenta (Metro, EAS, prebuild) a consuma - sem Promises, sem assincronismo.
Campos na configuração pública são incorporados aos builds e disponíveis via Constants.expoConfig. Chaves sensíveis (hooks, ios.config, android.config, campos de assinatura de atualização) são filtradas.
Plugins de configuração declarados em plugins são executados durante npx expo prebuild e EAS Build para mutar projetos nativos.

Ordem de Resolução da Configuração

Etapa	Fonte	Notas
1	`app.config.json` ou `app.json`	Linha de base estática; ferramentas CLI podem editar `app.json` automaticamente
2	`app.config.ts` (preferido) ou `app.config.js`	Se TS e JS existirem, TypeScript vence
3	Mesclagem de função	`export default ({ config }) => ({ ...config, ... })`
4	Wrapper `expo: {}`	Se presente na raiz, apenas o objeto `expo` aninhado é usado

# Configuração completa resolvida (inclui campos apenas nativos)
npx expo config
 
# Subconjunto público - corresponde ao que o JS pode ler em tempo de execução
npx expo config --type public

Estratégias de Ambiente

Mecanismo	Executa quando	Seguro para segredos	Lido no aplicativo via
`EXPO_PUBLIC_*` em `.env`	`expo start`, `expo export`, bundling Metro do EAS	Não - incorporado ao bundle JS	`process.env.EXPO_PUBLIC_API_URL`
`APP_ENV` / variáveis de shell personalizadas	Avaliação de `app.config.ts`	Sim (apenas tempo de build, não incorporado automaticamente)	`extra` → `Constants.expoConfig.extra`
Variáveis de ambiente / segredos do EAS	Servidores EAS Build	Segredos sim (lado do servidor)	Injetado em `extra` no tempo de build
Campo `extra`	Gravado no manifesto	Não - enviado no binário	`Constants.expoConfig.extra`

// .env.development (commitado - sem segredos)
EXPO_PUBLIC_API_URL=http://localhost:4000
APP_ENV=development

// Código de recurso - EXPO_PUBLIC_ deve usar notação de ponto (necessário para inlining)
const url = process.env.EXPO_PUBLIC_API_URL; // ✓
// const url = process.env["EXPO_PUBLIC_API_URL"]; // ✗ não será inlined

Regras Seguras Contra Segredos

Nunca coloque chaves de API, segredos de cliente OAuth ou material de assinatura privado em EXPO_PUBLIC_*, extra ou app.json commitado.
Sim, mantenha segredos do lado do servidor no EAS Secrets e passe apenas tokens derivados e com escopo para o cliente quando inevitável.
Sim, adicione .env*.local ao .gitignore para substituições específicas da máquina.
Não import app.json no código de recursos - use Constants.expoConfig para ler o manifesto processado.
Audite com npx expo config --type public antes de cada lançamento.

Superfícies de Configuração Comuns

Campo	Propósito
`name` / `slug`	Nome de exibição e segmento de URL do projeto Expo
`scheme`	Esquema de deep link (`acme://`)
`ios.bundleIdentifier` / `android.package`	Identidade do armazenamento - deve diferir por ambiente ao instalar lado a lado
`plugins`	Mutações nativas (permissões, entitlements, alterações Gradle/Pod)
`updates.url` / `runtimeVersion`	Direcionamento do EAS Update
`extra`	JSON arbitrário para tempo de execução - trate como público

Notas de TypeScript

// types/expo-extra.ts - compartilhe a forma Extra entre app.config e tempo de execução
export type AppExtra = {
  appEnv: "development" | "staging" | "production";
  apiUrl: string;
};
 
// app.config.ts
import { ExpoConfig, ConfigContext } from "expo/config";
import type { AppExtra } from "./types/expo-extra";
 
export default ({ config }: ConfigContext): ExpoConfig => {
  const extra: AppExtra = {
    appEnv: "development",
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:4000",
  };
  return { ...config, extra };
};

Use tsx para que app.config.ts possa import módulos locais do TypeScript e plugins de configuração.

Armadilhas

Segredos em EXPO_PUBLIC_ ou extra - Ambos acabam no bundle do cliente; qualquer pessoa pode extraí-los. Correção: Mantenha segredos no seu servidor; use tokens de curta duração; armazene segredos de build apenas no EAS Secrets.
Desestruturação de process.env - const { EXPO_PUBLIC_X } = process.env não é inlined pelo Metro. Correção: Sempre use a notação de ponto process.env.EXPO_PUBLIC_X no código do aplicativo.
Importar app.config.ts de componentes - Traz lógica apenas do Node para o Metro e pode vazar o tratamento de ambiente em tempo de build. Correção: Leia Constants.expoConfig ou process.env.EXPO_PUBLIC_* apenas no código do aplicativo.
Esperar que app.config recarregue como Fast Refresh - A configuração é reavaliada quando o Metro reinicia, não a cada hot reload. Correção: Reinicie expo start após alterar app.config.ts; recarregue completamente o aplicativo para alterações em EXPO_PUBLIC_.
Mesmo ID de bundle entre staging e production - Instalar ambos os builds em um dispositivo sobrescreve o outro. Correção: Sufixe identificadores (com.acme.mobile.staging) por ambiente.
Promises na configuração dinâmica - export default async () => ({}) é inválido; a configuração deve retornar de forma síncrona. Correção: Leia variáveis de ambiente de forma síncrona; busque configuração remota da sua API em tempo de execução do aplicativo.
Confiar em NODE_ENV para escolher arquivos .env - expo export e eas update forçam NODE_ENV=production. Correção: Use APP_ENV explícito ou eas env:pull para alternância de ambiente.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Apenas `app.json`	Aplicativos simples; sem ramificação de ambiente	Múltiplos ambientes ou configuração dinâmica tipada
`app.config.ts` + `extra`	Nomes, IDs, flags de recursos específicos do ambiente	Você só precisa de ícones estáticos e slug
Arquivos `.env` `EXPO_PUBLIC_`	URLs de API seguros para o cliente e alternância de recursos	Chaves privadas ou segredos por usuário
Variáveis de ambiente EAS	Builds CI/CD com segredos mantidos no servidor	Prototipagem pura local com Expo Go sem EAS
Configuração remota (Firebase, LaunchDarkly)	Alterar flags sem reconstruir	Constantes de tempo de build como identificador de bundle
`react-native-config` (bare)	RN bare legado sem suporte a ambiente Expo	Novos projetos Expo SDK 57 - use `EXPO_PUBLIC_`

FAQs

Qual é a diferença entre app.json e app.config.js?

app.json é JSON estático que as ferramentas podem atualizar automaticamente. app.config.js / app.config.ts é dinâmico - suporta variáveis, ramificação de ambiente e TypeScript. O Expo mescla o estático no dinâmico quando você exporta uma função.

Qual arquivo deve conter minha configuração?

Mantenha um app.json mínimo se as ferramentas o esperarem, mas prefira app.config.ts como a fonte da verdade para qualquer coisa dependente do ambiente. Execute npx expo config para ver o resultado mesclado.

Como leio valores de configuração dentro do meu aplicativo React Native?

Use expo-constants:

import Constants from "expo-constants";
const apiUrl = Constants.expoConfig?.extra?.apiUrl;

Para variáveis EXPO_PUBLIC_, use process.env.EXPO_PUBLIC_API_URL diretamente nos arquivos de origem.

Por que não devo importar app.json em componentes?

Importações diretas contornam o pipeline de processamento de configuração do Expo e podem empacotar o conteúdo bruto do arquivo. Constants.expoConfig retorna o manifesto resolvido e seguro para o público usado nos builds.

O que o npx expo config --type public mostra?

O subconjunto de configuração incorporado ao seu aplicativo e exposto ao JavaScript - a mesma forma disponível através de Constants.expoConfig. Use-o para auditar vazamentos antes do lançamento.

Como funcionam as variáveis de ambiente EXPO_PUBLIC_?

O Expo CLI carrega arquivos .env e incorpora referências process.env.EXPO_PUBLIC_* ao seu bundle JavaScript no momento do build. Eles são visíveis para os usuários finais - nunca armazene segredos lá.

Para que serve o campo extra?

extra é um objeto JSON arbitrário copiado para o manifesto público. Passe flags de recursos, rótulos de ambiente ou endpoints não sensíveis. Leia-o via Constants.expoConfig.extra.

Como configuro diferentes IDs de bundle por ambiente?

Ramifique em app.config.ts com base em APP_ENV:

ios: {
  bundleIdentifier:
    env === "production" ? "com.acme.app" : "com.acme.app.staging",
},

Defina APP_ENV ao executar eas build ou localmente no seu shell.

O app.config.ts pode usar async/await ou fetch?

Não. A configuração dinâmica deve retornar um objeto simples de forma síncrona - sem Promises. Busque configurações remotas da sua API após o lançamento do aplicativo em JavaScript.

Armadilha: Por que minha variável EXPO_PUBLIC_ apareceu como undefined?

Causas comuns: prefixo EXPO_PUBLIC_ ausente, uso de notação de colchetes (process.env['EXPO_PUBLIC_X']), ou esquecer de reiniciar o Metro após alterar .env. Corrija o prefixo, use notação de ponto e execute npx expo start --clear.

Como os plugins de configuração se relacionam com app.config?

Liste os nomes ou caminhos dos plugins no array plugins. Eles são executados durante o prebuild/EAS Build para modificar projetos nativos (permissões, entitlements, Gradle). Eles não são executados no Expo Go para código nativo que ainda não está empacotado lá.

Devo fazer commit dos arquivos .env?

Faça commit de .env com padrões não secretos, se útil. Nunca faça commit de .env.local ou arquivos com credenciais. Adicione .env*.local ao .gitignore.

Como APP_ENV difere de NODE_ENV?

NODE_ENV é controlado pelo Node e pelos bundlers - expo export força production. APP_ENV é uma variável personalizada que você controla para alternar entre staging/production em app.config.ts sem conflitar com as ferramentas.

Quais campos são filtrados da configuração pública?

hooks, ios.config, android.config e campos de assinatura de código do EAS Update são removidos de Constants.expoConfig. Não confie em lê-los do JS.

Como tipar expoConfig.extra em TypeScript?

Defina um tipo AppExtra compartilhado e faça o cast:

import Constants from "expo-constants";
import type { AppExtra } from "../types/expo-extra";
const extra = Constants.expoConfig?.extra as AppExtra;

Mantenha o tipo em um arquivo importado tanto por app.config.ts quanto pelo código de tempo de execução.

Relacionados

Guia de Início Rápido do create-expo-app - scaffold antes de configurar o aplicativo
Ambientes e Variáveis de Ambiente EAS - segredos do lado do EAS e fluxos de pull de ambiente
Expo Go vs Builds de Desenvolvimento - quais campos de configuração o Expo Go pode realmente exercitar
Atualizando Versões do SDK do Expo - alterações no esquema de configuração entre versões principais do SDK
Núcleo de Módulos Expo - como os módulos nativos consomem configuração no tempo de build
Melhores Práticas - higiene de lançamento e cadência de revisão de configuração

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.

// app.config.ts
import { ExpoConfig, ConfigContext } from "expo/config";
 
const APP_ENV = process.env.APP_ENV ?? "development";
 
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: APP_ENV === "production" ? "Acme" : "Acme (Dev)",
  slug: "acme-mobile",
  scheme: "acme",
  extra: {
    appEnv: APP_ENV,
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "https://staging.api.acme.test",
  },
  ios: { bundleIdentifier: "com.acme.mobile" },
  android: { package: "com.acme.mobile" },
});

# Inspecione o manifesto público resolvido (o que Constants.expoConfig exporá)
APP_ENV=development EXPO_PUBLIC_API_URL=https://staging.api.acme.test npx expo config --type public

Quando usar isso:

Definir identificadores de bundle, ícones, splash screen, scheme de deep-link e configurações do EAS Update.
Ramificar o nome do aplicativo, URLs de API ou flags de recursos por ambiente sem manter três repositórios.
Passar valores não secretos de tempo de execução para JS via extra e Constants.expoConfig.
Registrar plugins de configuração que modificam android/ e ios/ durante o prebuild.

Exemplo de Trabalho

// app.config.ts - staging vs production com padrões seguros contra segredos
import { ExpoConfig, ConfigContext } from "expo/config";
 
type AppEnv = "development" | "staging" | "production";
 
function resolveEnv(): AppEnv {
  const raw = process.env.APP_ENV ?? "development";
  if (raw === "staging" || raw === "production") return raw;
  return "development";
}
 
const env = resolveEnv();
 
const apiUrlByEnv: Record<AppEnv, string> = {
  development: "http://localhost:4000",
  staging: "https://staging.api.acme.test",
  production: "https://api.acme.com",
};
 
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: env === "production" ? "Acme" : `Acme (${env})`,
  slug: "acme-mobile",
  scheme: "acme",
  version: "1.4.0",
  orientation: "portrait",
  userInterfaceStyle: "automatic",
  plugins: ["expo-router"],
  extra: {
    appEnv: env,
    // Apenas valores não secretos - legíveis no aplicativo compilado
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? apiUrlByEnv[env],
    featureFlags: {
      newCheckout: env !== "production",
    },
  },
  ios: {
    bundleIdentifier:
      env === "production" ? "com.acme.mobile" : `com.acme.mobile.${env}`,
    supportsTablet: true,
  },
  android: {
    package: env === "production" ? "com.acme.mobile" : `com.acme.mobile.${env}`,
    adaptiveIcon: {
      foregroundImage: "./assets/adaptive-icon.png",
      backgroundColor: "#ffffff",
    },
  },
});

// src/config/runtime.ts - leia a configuração resolvida em tempo de execução (não app.config.ts bruto)
import Constants from "expo-constants";
 
type Extra = {
  appEnv: "development" | "staging" | "production";
  apiUrl: string;
  featureFlags: { newCheckout: boolean };
};
 
const extra = Constants.expoConfig?.extra as Extra;
 
export const appEnv = extra.appEnv;
export const apiUrl = extra.apiUrl;
export const featureFlags = extra.featureFlags;

# Desenvolvimento local (API de staging)
APP_ENV=staging EXPO_PUBLIC_API_URL=https://staging.api.acme.test npx expo start
 
# Build de produção EAS - segredos vivem no EAS, não em app.config
APP_ENV=production eas build --profile production --platform ios

O que isso demonstra:

app.config.ts mescla valores estáticos de app.json usando o padrão de middleware ({ config }).
APP_ENV alterna identificadores nativos e nome de exibição por ambiente.
Variáveis EXPO_PUBLIC_* são incorporadas ao JS no momento do bundle; extra expõe a configuração via Constants.expoConfig.
npx expo config --type public pré-visualiza o manifesto visível para o cliente antes do envio.

Mergulho Profundo

Como Funciona

O Expo CLI procura por configuração estática (app.json ou app.config.json) e configuração dinâmica (app.config.js / app.config.ts). Se ambos existirem, o dinâmico prevalece após a mesclagem.
Se a configuração dinâmica exportar uma função, o Expo passa a configuração estática normalizada como { config } e usa o valor de retorno como o manifesto final.
A configuração resolvida é serializada para JSON antes que qualquer ferramenta (Metro, EAS, prebuild) a consuma - sem Promises, sem assincronismo.
Campos na configuração pública são incorporados aos builds e disponíveis via Constants.expoConfig. Chaves sensíveis (hooks, ios.config, android.config, campos de assinatura de atualização) são filtradas.
Plugins de configuração declarados em plugins são executados durante npx expo prebuild e EAS Build para mutar projetos nativos.

Ordem de Resolução da Configuração

Etapa	Fonte	Notas
1	`app.config.json` ou `app.json`	Linha de base estática; ferramentas CLI podem editar `app.json` automaticamente
2	`app.config.ts` (preferido) ou `app.config.js`	Se TS e JS existirem, TypeScript vence
3	Mesclagem de função	`export default ({ config }) => ({ ...config, ... })`
4	Wrapper `expo: {}`	Se presente na raiz, apenas o objeto `expo` aninhado é usado

# Configuração completa resolvida (inclui campos apenas nativos)
npx expo config
 
# Subconjunto público - corresponde ao que o JS pode ler em tempo de execução
npx expo config --type public

Estratégias de Ambiente

Mecanismo	Executa quando	Seguro para segredos	Lido no aplicativo via
`EXPO_PUBLIC_*` em `.env`	`expo start`, `expo export`, bundling Metro do EAS	Não - incorporado ao bundle JS	`process.env.EXPO_PUBLIC_API_URL`
`APP_ENV` / variáveis de shell personalizadas	Avaliação de `app.config.ts`	Sim (apenas tempo de build, não incorporado automaticamente)	`extra` → `Constants.expoConfig.extra`
Variáveis de ambiente / segredos do EAS	Servidores EAS Build	Segredos sim (lado do servidor)	Injetado em `extra` no tempo de build
Campo `extra`	Gravado no manifesto	Não - enviado no binário	`Constants.expoConfig.extra`

// .env.development (commitado - sem segredos)
EXPO_PUBLIC_API_URL=http://localhost:4000
APP_ENV=development

// Código de recurso - EXPO_PUBLIC_ deve usar notação de ponto (necessário para inlining)
const url = process.env.EXPO_PUBLIC_API_URL; // ✓
// const url = process.env["EXPO_PUBLIC_API_URL"]; // ✗ não será inlined

Regras Seguras Contra Segredos

Nunca coloque chaves de API, segredos de cliente OAuth ou material de assinatura privado em EXPO_PUBLIC_*, extra ou app.json commitado.
Sim, mantenha segredos do lado do servidor no EAS Secrets e passe apenas tokens derivados e com escopo para o cliente quando inevitável.
Sim, adicione .env*.local ao .gitignore para substituições específicas da máquina.
Não import app.json no código de recursos - use Constants.expoConfig para ler o manifesto processado.
Audite com npx expo config --type public antes de cada lançamento.

Superfícies de Configuração Comuns

Campo	Propósito
`name` / `slug`	Nome de exibição e segmento de URL do projeto Expo
`scheme`	Esquema de deep link (`acme://`)
`ios.bundleIdentifier` / `android.package`	Identidade do armazenamento - deve diferir por ambiente ao instalar lado a lado
`plugins`	Mutações nativas (permissões, entitlements, alterações Gradle/Pod)
`updates.url` / `runtimeVersion`	Direcionamento do EAS Update
`extra`	JSON arbitrário para tempo de execução - trate como público

Notas de TypeScript

// types/expo-extra.ts - compartilhe a forma Extra entre app.config e tempo de execução
export type AppExtra = {
  appEnv: "development" | "staging" | "production";
  apiUrl: string;
};
 
// app.config.ts
import { ExpoConfig, ConfigContext } from "expo/config";
import type { AppExtra } from "./types/expo-extra";
 
export default ({ config }: ConfigContext): ExpoConfig => {
  const extra: AppExtra = {
    appEnv: "development",
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:4000",
  };
  return { ...config, extra };
};

Use tsx para que app.config.ts possa import módulos locais do TypeScript e plugins de configuração.

Armadilhas

Segredos em EXPO_PUBLIC_ ou extra - Ambos acabam no bundle do cliente; qualquer pessoa pode extraí-los. Correção: Mantenha segredos no seu servidor; use tokens de curta duração; armazene segredos de build apenas no EAS Secrets.
Desestruturação de process.env - const { EXPO_PUBLIC_X } = process.env não é inlined pelo Metro. Correção: Sempre use a notação de ponto process.env.EXPO_PUBLIC_X no código do aplicativo.
Importar app.config.ts de componentes - Traz lógica apenas do Node para o Metro e pode vazar o tratamento de ambiente em tempo de build. Correção: Leia Constants.expoConfig ou process.env.EXPO_PUBLIC_* apenas no código do aplicativo.
Esperar que app.config recarregue como Fast Refresh - A configuração é reavaliada quando o Metro reinicia, não a cada hot reload. Correção: Reinicie expo start após alterar app.config.ts; recarregue completamente o aplicativo para alterações em EXPO_PUBLIC_.
Mesmo ID de bundle entre staging e production - Instalar ambos os builds em um dispositivo sobrescreve o outro. Correção: Sufixe identificadores (com.acme.mobile.staging) por ambiente.
Promises na configuração dinâmica - export default async () => ({}) é inválido; a configuração deve retornar de forma síncrona. Correção: Leia variáveis de ambiente de forma síncrona; busque configuração remota da sua API em tempo de execução do aplicativo.
Confiar em NODE_ENV para escolher arquivos .env - expo export e eas update forçam NODE_ENV=production. Correção: Use APP_ENV explícito ou eas env:pull para alternância de ambiente.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Apenas `app.json`	Aplicativos simples; sem ramificação de ambiente	Múltiplos ambientes ou configuração dinâmica tipada
`app.config.ts` + `extra`	Nomes, IDs, flags de recursos específicos do ambiente	Você só precisa de ícones estáticos e slug
Arquivos `.env` `EXPO_PUBLIC_`	URLs de API seguros para o cliente e alternância de recursos	Chaves privadas ou segredos por usuário
Variáveis de ambiente EAS	Builds CI/CD com segredos mantidos no servidor	Prototipagem pura local com Expo Go sem EAS
Configuração remota (Firebase, LaunchDarkly)	Alterar flags sem reconstruir	Constantes de tempo de build como identificador de bundle
`react-native-config` (bare)	RN bare legado sem suporte a ambiente Expo	Novos projetos Expo SDK 57 - use `EXPO_PUBLIC_`

FAQs

Qual é a diferença entre app.json e app.config.js?

Qual arquivo deve conter minha configuração?

Como leio valores de configuração dentro do meu aplicativo React Native?

Use expo-constants:

import Constants from "expo-constants";
const apiUrl = Constants.expoConfig?.extra?.apiUrl;

Para variáveis EXPO_PUBLIC_, use process.env.EXPO_PUBLIC_API_URL diretamente nos arquivos de origem.

Por que não devo importar app.json em componentes?

O que o npx expo config --type public mostra?

Como funcionam as variáveis de ambiente EXPO_PUBLIC_?

Para que serve o campo extra?

extra é um objeto JSON arbitrário copiado para o manifesto público. Passe flags de recursos, rótulos de ambiente ou endpoints não sensíveis. Leia-o via Constants.expoConfig.extra.

Como configuro diferentes IDs de bundle por ambiente?

Ramifique em app.config.ts com base em APP_ENV:

ios: {
  bundleIdentifier:
    env === "production" ? "com.acme.app" : "com.acme.app.staging",
},

Defina APP_ENV ao executar eas build ou localmente no seu shell.

O app.config.ts pode usar async/await ou fetch?

Não. A configuração dinâmica deve retornar um objeto simples de forma síncrona - sem Promises. Busque configurações remotas da sua API após o lançamento do aplicativo em JavaScript.

Armadilha: Por que minha variável EXPO_PUBLIC_ apareceu como undefined?

Como os plugins de configuração se relacionam com app.config?

Devo fazer commit dos arquivos .env?

Faça commit de .env com padrões não secretos, se útil. Nunca faça commit de .env.local ou arquivos com credenciais. Adicione .env*.local ao .gitignore.

Como APP_ENV difere de NODE_ENV?

Quais campos são filtrados da configuração pública?

hooks, ios.config, android.config e campos de assinatura de código do EAS Update são removidos de Constants.expoConfig. Não confie em lê-los do JS.

Como tipar expoConfig.extra em TypeScript?

Defina um tipo AppExtra compartilhado e faça o cast:

import Constants from "expo-constants";
import type { AppExtra } from "../types/expo-extra";
const extra = Constants.expoConfig?.extra as AppExtra;

Mantenha o tipo em um arquivo importado tanto por app.config.ts quanto pelo código de tempo de execução.

Relacionados

Guia de Início Rápido do create-expo-app - scaffold antes de configurar o aplicativo
Ambientes e Variáveis de Ambiente EAS - segredos do lado do EAS e fluxos de pull de ambiente
Expo Go vs Builds de Desenvolvimento - quais campos de configuração o Expo Go pode realmente exercitar
Atualizando Versões do SDK do Expo - alterações no esquema de configuração entre versões principais do SDK
Núcleo de Módulos Expo - como os módulos nativos consomem configuração no tempo de build
Melhores Práticas - higiene de lançamento e cadência de revisão de configuração

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).

app.json & app.config.js

Buscar na documentação

app.json & app.config.js