Pular para o conteúdo principal
Versão: 0.4.0

Arquivos Env

Carregue variáveis de ambiente de arquivos .env. Este é um padrão comum para gerenciar configuração, especialmente secrets que não devem ser commitados no controle de versão.

Uso Básico​

{
    name: "build"
    env: {
        files: [".env"]
    }
    implementations: [...]
}

Com um arquivo .env:

# .env
API_KEY=secret123
DATABASE_URL=postgres://localhost/mydb
DEBUG=false

Variáveis são carregadas e disponíveis no seu script.

Formato do Arquivo​

Formato .env padrão:

# Comments start with #
KEY=value

# Quoted values (spaces preserved)
MESSAGE="Hello World"
PATH_WITH_SPACES='/path/to/my file'

# Empty value
EMPTY_VAR=

# No value (same as empty)
NO_VALUE

# Multiline (use quotes)
MULTILINE="line1
line2
line3"

Arquivos Opcionais​

Sufixe com ? para tornar um arquivo opcional:

env: {
    files: [
        ".env",           // Required - error if missing
        ".env.local?",    // Optional - ignored if missing
        ".env.secrets?",  // Optional
    ]
}

Isso é útil para:

  • Sobrescritas locais que podem não existir
  • Arquivos específicos de ambiente
  • Configurações específicas de desenvolvedor

Ordem dos Arquivos​

Arquivos são carregados em ordem; arquivos posteriores sobrescrevem os anteriores:

env: {
    files: [
        ".env",           // Base config
        ".env.${ENV}?",   // Environment-specific overrides
        ".env.local?",    // Local overrides (highest priority)
    ]
}

Exemplo com ENV=production:

# .env
API_URL=http://localhost:3000
DEBUG=true

# .env.production
API_URL=https://api.example.com
DEBUG=false

# .env.local (developer override)
DEBUG=true

Resultado:

  • API_URL=https://api.example.com (de .env.production)
  • DEBUG=true (de .env.local)

Resolução de Caminho​

Caminhos são relativos à localização do invowkfile:

project/
├── invowkfile.cue
├── .env                  # files: [".env"]
├── config/
│   └── .env.prod         # files: ["config/.env.prod"]
└── src/

Para módulos, caminhos são relativos à raiz do módulo.

Interpolação de Variáveis​

Use ${VAR} para incluir outras variáveis de ambiente:

env: {
    files: [
        ".env",
        ".env.${NODE_ENV}?",    // Uses NODE_ENV value
        ".env.${USER}?",        // Uses current user
    ]
}
# If NODE_ENV=production, loads:
# - .env
# - .env.production (if exists)
# - .env.john (if exists and USER=john)

Níveis de Escopo​

Arquivos env podem ser carregados em múltiplos níveis:

Nível Raiz​

env: {
    files: [".env"]  // Loaded for all commands
}

cmds: [...]

Nível de Comando​

{
    name: "build"
    env: {
        files: [".env.build"]  // Only for this command
    }
    implementations: [...]
}

Nível de Implementação​

{
    name: "build"
    implementations: [
        {
            script: "npm run build"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            env: {
                files: [".env.node"]  // Only for this implementation
            }
        }
    ]
}

Combinado com Variáveis​

Use ambos arquivos e variáveis diretas:

env: {
    files: [".env"]
    vars: {
        // These override values from .env
        OVERRIDE_VALUE: "from-invowkfile"
    }
}

Variáveis em vars sempre sobrescrevem valores de arquivos. Todos os arquivos são carregados primeiro (raiz → comando → implementação), depois todas as vars são aplicadas por cima. Veja Precedência para a ordem completa.

Sobrescrita via CLI​

Carregue arquivos adicionais em tempo de execução:

# Load extra file
invowk cmd build --ivk-env-file .env.custom

# Multiple files
invowk cmd build --ivk-env-file .env.custom --ivk-env-file .env.secrets

Arquivos da CLI têm a maior prioridade e sobrescrevem todas as fontes definidas no invowkfile.

Exemplos do Mundo Real​

Desenvolvimento vs Produção​

{
    name: "start"
    env: {
        files: [
            ".env",                    // Base config
            ".env.${NODE_ENV:-dev}?",  // Environment-specific
            ".env.local?",             // Local overrides
        ]
    }
    implementations: [{
        script: "node server.js"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Gerenciamento de Secrets​

{
    name: "deploy"
    env: {
        files: [
            ".env",                    // Non-sensitive config
            ".env.secrets?",           // Sensitive - not in git
        ]
    }
    implementations: [{
        script: """
            echo "Deploying with API_KEY..."
            ./deploy.sh
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

.gitignore:

.env.secrets
.env.local

Multi-Ambiente​

project/
├── invowkfile.cue
├── .env                  # Shared defaults
├── .env.development      # Dev settings
├── .env.staging          # Staging settings
└── .env.production       # Production settings
{
    name: "deploy"
    env: {
        files: [
            ".env",
            ".env.${DEPLOY_ENV}",  // DEPLOY_ENV must be set
        ]
    }
    depends_on: {
        env_vars: [
            {alternatives: [{name: "DEPLOY_ENV", validation: "^(development|staging|production)$"}]}
        ]
    }
    implementations: [...]
}

Melhores Práticas​

  1. Use .env para padrões: Configuração base que funciona para todos
  2. Use .env.local para sobrescritas: Configurações específicas de desenvolvedor, não no git
  3. Use .env.{environment} para ambientes: Produção, staging, etc.
  4. Marque arquivos sensíveis como opcionais: Podem não existir em todos os ambientes
  5. Não commite secrets: Adicione .env.secrets, .env.local ao .gitignore

Próximos Passos​