expo-local-builder

CLI para builds Android locais de projetos Expo/React Native sem dependência do EAS Build.

🚀 Funcionalidades

• ✅ Builds locais rápidos - Gera APKs debug e release direto na sua máquina
• ✅ Versionamento automático - Sincroniza versões entre package.json, build.gradle e app.config
• ✅ Organização de APKs - Nomenclatura padronizada com versão e timestamp
• ✅ Independência do EAS - Sem filas, sem uploads, sem limites de plano gratuito
• ✅ Multiplataforma - Funciona em Windows, macOS e Linux

📦 Instalação

Uso global (recomendado)

npm install -g expo-local-builder

Uso via npx (sem instalação)

npx expo-local-builder <comando>

Instalação no projeto

npm install --save-dev expo-local-builder

🎯 Uso

Para Projetos com Pasta android/ (Bare Workflow)

# Build release
expo-builder build release

# Build debug
expo-builder build debug

Para Projetos Expo Managed (sem pasta android/)

Se seu projeto não tem a pasta android/, use a flag --prebuild:

# Gera pasta android/ automaticamente e faz build
expo-builder build release --prebuild

# Ou gere a pasta manualmente primeiro:
npx expo prebuild
expo-builder build release

Incrementar Versão

# Patch: 1.0.0 → 1.0.1
expo-builder bump patch

# Minor: 1.0.0 → 1.1.0
expo-builder bump minor

# Major: 1.0.0 → 2.0.0
expo-builder bump major

Sincronizar Versões

expo-builder sync

Sincroniza a versão do package.json para:

• android/app/build.gradle (versionCode + versionName)
• app.config.ts ou app.config.js (APP_VERSION)

📁 Estrutura de Outputs

APKs são organizados em builds/android/:

seu-projeto/
├── builds/
│   └── android/
│       ├── debug/
│       │   └── MeuApp-v1.0.0-debug-2026-04-28T14-35-32.apk
│       └── release/
│           └── MeuApp-v1.0.0-release-2026-04-28T14-36-15.apk

⚙️ Opções

Comando build

expo-builder build <type> [options]

Argumentos:
  type                debug ou release

Options:
  -o, --output <dir>  Diretório de output dos APKs (padrão: "builds")
  --no-sync          Não sincronizar versões antes do build
  --prebuild         Executar expo prebuild se necessário (para Expo Managed)

Exemplo com todas as opções:

expo-builder build release --output dist --prebuild

Comando bump

expo-builder bump <type> [options]

Options:
  --no-sync  Não sincronizar versões após bump

🔧 Requisitos

• Node.js >= 14.0.0
• Projeto Expo/React Native com diretório android/
• Gradle configurado (incluído no projeto Expo)
• Android SDK instalado

📝 Workflow Recomendado

# 1. Fazer alterações no código
# ...

# 2. Incrementar versão (se necessário)
expo-builder bump patch

# 3. Gerar build
expo-builder build release

# 4. APK estará em builds/android/release/

🔄 Integração com package.json

Adicione scripts ao seu package.json:

{
  "scripts": {
    "build:android:release": "expo-builder build release",
    "build:android:debug": "expo-builder build debug",
    "version:bump:patch": "expo-builder bump patch",
    "version:bump:minor": "expo-builder bump minor",
    "version:bump:major": "expo-builder bump major"
  }
}

Depois use:

npm run build:android:release
npm run version:bump:patch

🆚 Expo Builder vs EAS Build

| Característica | Expo Builder | EAS Build | |----------------|--------------|-----------| | Velocidade | 5-10 min ⚡ | 20-40 min (com fila) | | Custo | Grátis 💰 | Limitado no plano free | | Privacidade | Código local 🔒 | Upload para servidores Expo | | Debugging | Logs diretos do Gradle 🔍 | Logs remotos | | Internet | Apenas para deps ☁️ | Upload completo do projeto | | CI/CD | Fácil integração 🔄 | Requer configuração EAS |

📚 Versionamento

O expo-local-builder usa package.json como fonte única de verdade para versionamento.

Cálculo de versionCode:

versionCode = MAJOR * 10000 + MINOR * 100 + PATCH

Exemplos:

• 1.0.0 → 10000
• 1.2.3 → 10203
• 2.5.10 → 20510

🛡️ Keystore de Produção

Por padrão, projetos Expo usam debug.keystore para ambos debug e release.

Para produção real, gere um keystore próprio:

keytool -genkeypair -v -storetype PKCS12 \
  -keystore meu-app-release.keystore \
  -alias meu-app \
  -keyalg RSA -keysize 2048 -validity 10000

Configure em android/app/build.gradle:

signingConfigs {
    release {
        storeFile file('meu-app-release.keystore')
        storePassword 'SUA_SENHA_SEGURA'
        keyAlias 'meu-app'
        keyPassword 'SUA_SENHA_SEGURA'
    }
}

🤝 Compatibilidade

O expo-builder não interfere com EAS Build. Você pode usar ambos:

# Build local
expo-builder build release

# Build no EAS
eas build --platform android --profile production

❓ FAQ

Erro: "Diretório android/ não encontrado"

Seu projeto usa Expo Managed Workflow. Escolha uma das opções:

Opção 1: Use a flag --prebuild:

expo-builder build release --prebuild

Opção 2: Gere a pasta android/ manualmente:

npx expo prebuild
expo-builder build release

Como usar em projetos React Native puro (sem Expo)?

Funciona perfeitamente! Apenas certifique-se de ter a pasta android/ no projeto:

expo-builder build release

Posso usar em múltiplos projetos?

Sim! Instale globalmente e use em qualquer projeto:

npm install -g expo-local-builder
cd projeto-1 && expo-builder build release
cd projeto-2 && expo-builder build debug

📄 Licença

MIT © Julio Prior

🐛 Reportar Problemas

Encontrou um bug? Abra uma issue

🙋 Ajuda

expo-builder --help
expo-builder build --help
expo-builder bump --help

Feito com ❤️ para a comunidade Expo/React Native