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

Variáveis de Ambiente

Defina variáveis de ambiente diretamente no seu invowkfile. Estas ficam disponíveis para seus scripts durante a execução.

Uso Básico​

{
    name: "build"
    env: {
        vars: {
            NODE_ENV: "production"
            API_URL: "https://api.example.com"
            DEBUG: "false"
        }
    }
    implementations: [{
        script: """
            echo "Building for $NODE_ENV"
            echo "Date: $BUILD_DATE"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Sintaxe de Variáveis​

Variáveis são pares chave-valor de strings:

vars: {
    // Simple values
    NAME: "value"
    
    // Numbers (still strings in shell)
    PORT: "3000"
    TIMEOUT: "30"
    
    // Boolean-like (strings "true"/"false")
    DEBUG: "true"
    VERBOSE: "false"
    
    // Paths
    CONFIG_PATH: "/etc/myapp/config.yaml"
    OUTPUT_DIR: "./dist"
    
    // URLs
    API_URL: "https://api.example.com"
}

Todos os valores são strings. O shell interpreta conforme necessário.

Referenciando Outras Variáveis​

Referencie variáveis de ambiente do sistema:

vars: {
    // Use system variable
    HOME_CONFIG: "${HOME}/.config/myapp"
    
    // With default value
    LOG_LEVEL: "${LOG_LEVEL:-info}"
    
    // Combine variables
    FULL_PATH: "${HOME}/projects/${PROJECT_NAME}"
}

Nota: Referências são expandidas em tempo de execução, não no momento da definição.

Níveis de Escopo​

Nível Raiz​

Disponível para todos os comandos:

env: {
    vars: {
        PROJECT_NAME: "myproject"
        VERSION: "1.0.0"
    }
}

cmds: [
    {
        name: "build"
        // Gets PROJECT_NAME and VERSION
        implementations: [...]
    },
    {
        name: "deploy"
        // Also gets PROJECT_NAME and VERSION
        implementations: [...]
    }
]

Nível de Comando​

Disponível para comando específico:

{
    name: "build"
    env: {
        vars: {
            BUILD_MODE: "release"
        }
    }
    implementations: [...]
}

Nível de Implementação​

Disponível para implementação específica:

{
    name: "build"
    implementations: [
        {
            script: "npm run build"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            env: {
                vars: {
                    NODE_ENV: "production"
                }
            }
        },
        {
            script: "go build ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            env: {
                vars: {
                    CGO_ENABLED: "0"
                }
            }
        }
    ]
}

Nível de Plataforma​

Variáveis por plataforma:

// Platform-specific env requires separate implementations
implementations: [
    {
        script: "echo $PLATFORM_CONFIG"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}]
        env: {
            vars: {
                PLATFORM_CONFIG: "/etc/myapp"
                PLATFORM_NAME: "Linux"
            }
        }
    },
    {
        script: "echo $PLATFORM_CONFIG"
        runtimes: [{name: "native"}]
        platforms: [{name: "macos"}]
        env: {
            vars: {
                PLATFORM_CONFIG: "/usr/local/etc/myapp"
                PLATFORM_NAME: "macOS"
            }
        }
    },
    {
        script: "echo %PLATFORM_CONFIG%"
        runtimes: [{name: "native"}]
        platforms: [{name: "windows"}]
        env: {
            vars: {
                PLATFORM_CONFIG: "%APPDATA%myapp"
                PLATFORM_NAME: "Windows"
            }
        }
    }
]

Combinado com Arquivos​

Variáveis sobrescrevem valores de arquivos env:

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

Sobrescrita via CLI​

Sobrescreva em tempo de execução:

# Single variable
invowk cmd build --ivk-env-var NODE_ENV=development

# Multiple variables
invowk cmd build --ivk-env-var NODE_ENV=dev --ivk-env-var DEBUG=true --ivk-env-var PORT=8080

Variáveis da CLI têm a maior prioridade.

Exemplos do Mundo Real​

Configuração de Build​

{
    name: "build"
    env: {
        vars: {
            NODE_ENV: "production"
            BUILD_TARGET: "es2020"
            SOURCEMAP: "false"
        }
    }
    implementations: [{
        script: "npm run build"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Configuração de API​

{
    name: "start"
    env: {
        vars: {
            API_HOST: "0.0.0.0"
            API_PORT: "3000"
            API_PREFIX: "/api/v1"
            CORS_ORIGIN: "*"
        }
    }
    implementations: [{
        script: "go run ./cmd/server"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Valores Dinâmicos​

{
    name: "release"
    env: {
        vars: {
            // Git-based version
            GIT_SHA: "$(git rev-parse --short HEAD)"
            GIT_BRANCH: "$(git branch --show-current)"
            
            // Timestamp
            BUILD_TIME: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
            
            // Combine values
            BUILD_ID: "${GIT_BRANCH}-${GIT_SHA}"
        }
    }
    implementations: [{
        script: """
            echo "Building $BUILD_ID at $BUILD_TIME"
            go build -ldflags="-X main.version=$BUILD_ID" ./...
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Configuração de Banco de Dados​

{
    name: "db migrate"
    env: {
        vars: {
            DB_HOST: "${DB_HOST:-localhost}"
            DB_PORT: "${DB_PORT:-5432}"
            DB_NAME: "${DB_NAME:-myapp}"
            DB_USER: "${DB_USER:-postgres}"
            // Construct URL from parts
            DATABASE_URL: "postgres://${DB_USER}@${DB_HOST}:${DB_PORT}/${DB_NAME}"
        }
    }
    implementations: [{
        script: "migrate -database $DATABASE_URL up"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Ambiente de Container​

Variáveis são passadas para containers:

{
    name: "build"
    env: {
        vars: {
            GOOS: "linux"
            GOARCH: "amd64"
            CGO_ENABLED: "0"
        }
    }
    implementations: [{
        script: "go build -o /workspace/bin/app ./..."
        runtimes: [{name: "container", image: "golang:1.26"}]
        platforms: [{name: "linux"}]
    }]
}

Melhores Práticas​

  1. Use padrões: ${VAR:-default} para config opcional
  2. Mantenha secrets fora: Não hardcode secrets; use arquivos env ou secrets externos
  3. Documente variáveis: Adicione comentários explicando cada variável
  4. Use nomenclatura consistente: Convenção UPPER_SNAKE_CASE
  5. Escopo apropriado: Raiz para compartilhado, comando para específico

Próximos Passos​