Noções Básicas de Configuração de Projeto

10 exemplos para você começar com a Configuração de Projeto - 7 básicos e 3 intermediários.

Pré-requisitos

Crie um app Expo com formato de produção e um pin explícito do SDK 57. O template default@sdk-57 inclui Expo Router, TypeScript e os scripts CLI recomendados.

npx create-expo-app@latest MyApp --template default@sdk-57
cd MyApp
npm install

Confirme o pin do SDK antes de adicionar recursos:

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Ferramentas: Estes exemplos visam Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Exemplos Básicos

1. Layout Padrão do Expo

Um projeto default@sdk-57 recém-criado é uma árvore pequena e previsível - aprenda esses caminhos antes de adicionar recursos ou pacotes de monorepo.

MyApp/
├── app/                    # Telas e layouts do Expo Router
│   ├── _layout.tsx         # Pilha raiz / provedores
│   ├── index.tsx           # Rota "/"
│   └── (tabs)/             # Grupo de abas (template inicial)
├── assets/                 # Ícones, splash, imagens referenciadas na configuração
├── app.config.ts           # Manifest dinâmico (nome, ID de bundle, plugins)
├── package.json            # Dependências com SDK fixado e scripts npm
├── tsconfig.json           # Estende expo/tsconfig.base
├── babel.config.js         # Preset do Expo para Metro
├── metro.config.js         # Ponto de entrada do bundler Metro (geralmente exportação padrão)
└── node_modules/

• app/ substitui um único App.tsx - nomes de arquivos mapeiam para rotas (app/settings.tsx → /settings)
• app/_layout.tsx é o layout raiz: envolva provedores, fontes e elementos de navegação aqui
• Arquivos em assets/ são referenciados por URI em app.config.ts (icon, splash) e importados em componentes
• Não há ios/ ou android/ no modo puramente gerenciado - eles aparecem após npx expo prebuild ou um build EAS

Relacionado: Templates do create-expo-app - trade-offs entre branco, abas e mínimo essencial | Estrutura de Pastas para Recursos - escalando além da árvore inicial

2. Pin do SDK em package.json

A versão do pacote expo é o contrato que todos os outros módulos Expo devem satisfazer.

{
  "name": "my-app",
  "version": "1.0.0",
  "main": "expo-router/entry",
  "private": true,
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web"
  },
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

• expo ~57.0.4 fixa o projeto ao SDK 57 - misturar módulos nativos do SDK 56 com expo do SDK 57 causa falhas na compilação
• main: "expo-router/entry" conecta o Metro à inicialização do Expo Router em vez de expo/AppEntry.js
• Fixe versões exatas de peers React e React Native mostradas no template - npx expo install as utiliza como base de compatibilidade
• Após clonar, execute npm install e depois npx expo-doctor antes de escrever código de recursos

Relacionado: Templates do create-expo-app - conjuntos de dependências específicos do template | ../expo-platform/create-expo-app-quickstart.md - flags de scaffold e checklist de verificação

3. Scripts do package.json

Os scripts padrão delegam para o Expo CLI para que todos os membros da equipe usem as mesmas flags do servidor de desenvolvimento.

{
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "lint": "expo lint",
    "typecheck": "tsc --noEmit"
  }
}

# Variantes comuns de start - passe flags após --
npm run start -- --clear          # limpa o cache do Metro após mudanças de dependência
npm run start -- --tunnel         # compartilha QR entre redes (mais lento)
npm run start -- --dev-client     # abre em um build de desenvolvimento personalizado
npm run ios                       # atalho para simulador

• expo start gerencia o Metro, o menu de desenvolvimento e os códigos QR - evite chamar react-native start diretamente em projetos Expo
• Scripts de plataforma (android, ios) são atalhos; eles ainda iniciam o Metro primeiro, depois abrem o alvo
• Adicione typecheck cedo para que o CI possa controlar mesclagens sem uma compilação nativa completa
• Use npx expo install <pkg> ao adicionar módulos nativos - ele lê a versão expo fixada e escolhe intervalos de semver compatíveis

Relacionado: Melhores Práticas de Configuração de Projeto - scripts que toda equipe deve padronizar

4. tsconfig.json

Estenda a configuração base de TypeScript do Expo, depois reforce as verificações sem quebrar a resolução de caminhos do Metro.

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    ".expo/types/**/*.ts",
    "expo-env.d.ts"
  ]
}

• extends: "expo/tsconfig.base" fornece os tipos jsx, moduleResolution e Expo Router corretos
• strict: true captura bugs de nulidade precocemente - crashes de celular são mais difíceis de depurar do que erros no console da web
• paths com @/* corresponde a aliases de importação comuns; o Metro lê o mesmo mapeamento via tsconfigPaths em templates Expo mais recentes
• Inclua .expo/types/**/*.ts para que as rotas tipadas geradas pelo Expo Router façam parte do tsc --noEmit

Relacionado: ../typescript-rn/expo-router-typed-routes/expo-router-typed-routes.md - rotas tipadas geradas em .expo/types

5. app.config.ts

app.config.ts é a única fonte de verdade para identidade do app, ícones, permissões e plugins de configuração.

import { ExpoConfig, ConfigContext } from "expo/config";
 
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: "My App",
  slug: "my-app",
  version: "1.0.0",
  orientation: "portrait",
  icon: "./assets/icon.png",
  scheme: "myapp",
  userInterfaceStyle: "automatic",
  newArchEnabled: true,
  ios: {
    supportsTablet: true,
    bundleIdentifier: "com.example.myapp",
  },
  android: {
    adaptiveIcon: {
      foregroundImage: "./assets/adaptive-icon.png",
      backgroundColor: "#ffffff",
    },
    package: "com.example.myapp",
  },
  plugins: ["expo-router"],
  experiments: {
    typedRoutes: true,
  },
});

• slug direciona URLs do painel Expo e canais de atualização - altere-o deliberadamente junto com name e IDs de bundle
• scheme registra prefixos de deep-link consumidos pelo Expo Router e expo-linking
• plugins são executados no momento do prebuild - eles são ignorados pelo Expo Go quando o plugin não está incluído no cliente
• Prefira app.config.ts em vez de app.json quando precisar de ramificação de ambiente sem confirmar segredos

Relacionado: ../expo-platform/expo-platform-basics/expo-platform-basics.md - visão geral do fluxo gerenciado e de configuração

6. expo-doctor

Execute expo-doctor após cada scaffold, clone ou aumento de dependência - ele compara seu grafo com o banco de dados de compatibilidade do SDK 57.

npx expo-doctor

# Caminho de correção típico quando o doctor relata descompasso de versão
npx expo install --fix
npx expo-doctor

Exemplo de saída para agir (não ignorar):

✖ expo-camera@15.0.0 - expected ~17.0.0 for SDK 57
✖ react-native-reanimated@3.16.0 - expected ~4.0.0 for SDK 57
 
› Run: npx expo install --fix

• Erros bloqueiam compilações confiáveis - módulos nativos com majors incompatíveis compilam em JS, mas falham em tempo de execução
• expo install --fix reescreve os intervalos do package.json para versões compatíveis com o SDK sem adivinhação manual de semver
• Reexecute o doctor após as correções até que o relatório esteja limpo (avisos merecem uma revisão da equipe, não ignorá-los silenciosamente)
• Adicione o doctor ao CI em pull requests para que o descompasso de versão nunca seja mesclado ao main

Relacionado: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md - atualizações intencionais do SDK

7. Conexão Metro e Babel

As configurações do Metro e Babel são mínimas em um app Expo padrão - mantenha-as mínimas, a menos que a resolução de monorepo exija alterações.

// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
  };
};

// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
 
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);
 
module.exports = config;

• babel-preset-expo habilita Reanimated, Expo Router e transformações de ambiente esperadas pelo SDK 57
• getDefaultConfig de expo/metro-config define resolver, transformer e extensões de assets para o SDK fixado
• Não copie configurações do Metro de blogs de React Native puro - os padrões do Expo já consideram o hashing de assets do expo
• Edite esses arquivos apenas ao adicionar watchFolders de monorepo ou resolvedores personalizados - consulte o guia de pacotes compartilhados antes de editar

Relacionado: Pacotes Compartilhados e Resolução do Metro - watchFolders e armadilhas de symlink

Exemplos Intermediários

8. Verificação na Primeira Execução

Um script de verificação curto captura desvios de SDK, erros de TypeScript e falhas de configuração antes que qualquer pessoa escreva código de recurso.

#!/usr/bin/env bash
# scripts/verify-first-run.sh
set -euo pipefail
 
echo "→ Verificando pin do SDK…"
node -e "
  const p = require('./package.json').dependencies;
  const expected = { expo: '~57.0.4', react: '19.2.3', 'react-native': '0.86.0' };
  for (const [k, v] of Object.entries(expected)) {
    if (p[k] !== v) throw new Error(\`Expected \${k}=\${v}, got \${p[k]}\`);
  }
  console.log('  Pin do SDK OK');
"
 
echo "→ Executando expo-doctor…"
npx expo-doctor
 
echo "→ Verificando tipos…"
npx tsc --noEmit
 
echo "→ Resolvendo configuração pública…"
npx expo config --type public | head -n 20
 
echo "✅ Verificações na primeira execução passaram - execute: npm run start"

chmod +x scripts/verify-first-run.sh
./scripts/verify-first-run.sh

• Execute isso após npm install em cada clone novo - arquivos de lockfile podem estar corretos enquanto o CLI global de um colega de equipe está desatualizado
• A asserção do pin do SDK falha rapidamente quando alguém cria um scaffold sem @sdk-57
• expo config --type public confirma que plugins e IDs de bundle são resolvidos - capture erros de digitação em app.config.ts precocemente
• Commite o script para que o onboarding seja um comando, não conhecimento tribal

Relacionado: ../expo-platform/create-expo-app-quickstart/create-expo-app-quickstart.md - script de scaffold reproduzível para a equipe

9. app.config.ts com Consciência de Ambiente

Ramifique a identidade do app com base em APP_VARIANT para que os builds de desenvolvimento, staging e produção coexistam sem repositórios separados.

import { ExpoConfig, ConfigContext } from "expo/config";
 
const APP_VARIANT = process.env.APP_VARIANT ?? "development";
 
const bundleSuffix = APP_VARIANT === "production" ? "" : `.${APP_VARIANT}`;
 
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: APP_VARIANT === "production" ? "My App" : `My App (${APP_VARIANT})`,
  slug: "my-app",
  ios: {
    bundleIdentifier: `com.example.myapp${bundleSuffix}`,
  },
  android: {
    package: `com.example.myapp${bundleSuffix}`,
  },
  extra: {
    appVariant: APP_VARIANT,
  },
});

# Inicie com uma variante - nome e ID de bundle mudam por comando
APP_VARIANT=development npx expo start
APP_VARIANT=staging npx expo run:ios
APP_VARIANT=production npx eas build --profile production --platform all

• APP_VARIANT é uma convenção da equipe - o Expo não a define; a consistência importa mais do que o nome exato
• IDs de bundle diferentes por variante permitem que o QA instale o staging ao lado da produção no mesmo dispositivo
• Exponha a variante em extra para que o código em tempo de execução possa controlar logs, URLs base da API ou flags de recursos
• Combine com perfis EAS de build que definem env.APP_VARIANT por canal - evite codificar URLs diretamente no código-fonte

Relacionado: Múltiplos Apps em um Único Repositório - white-label e apps específicos de flavor | ../expo-platform/environments-and-eas-environment-variables/environments-and-eas-environment-variables.md - segredos por ambiente

10. Higiene do Git e do Lockfile

Commite o lockfile e um .gitignore ciente de mobile no primeiro dia - instalações reproduzíveis importam para EAS e colegas de equipe.

# dependências
node_modules/
 
# Expo
.expo/
dist/
web-build/
 
# Nativo (fluxo gerenciado - gerado na compilação)
ios/
android/
 
# Segredos
.env
.env.*
!.env.example

git init
git add .
git commit -m "chore: scaffold MyApp (default@sdk-57)"

{
  "engines": {
    "node": ">=20.0.0"
  }
}

• Commite exatamente um lockfile (package-lock.json, yarn.lock ou pnpm-lock.yaml) - EAS o utiliza para reproduzir instalações
• Ignore .expo/ - estado de desenvolvimento local; não deve ser mesclado entre máquinas
• Ignore ios/ e android/ no fluxo gerenciado até que você adote intencionalmente a Geração Nativa Contínua (CNG) ou o fluxo bare
• Fixe engines.node para que o CI e os laptops executem o mesmo major do Node - as ferramentas do SDK 57 esperam Node 20+

Relacionado: Monorepo com Turborepo - estratégia de lockfile quando apps compartilham pacotes | Melhores Práticas de Configuração de Projeto - convenções que escalam além do primeiro sprint

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