O Bun lê seus arquivos .env automaticamente e fornece maneiras idiomáticas de ler e escrever suas variáveis de ambiente programaticamente. Além disso, alguns aspectos do comportamento do runtime do Bun podem ser configurados com variáveis de ambiente específicas do Bun.

Definindo variáveis de ambiente

O Bun lê os seguintes arquivos automaticamente (listados em ordem de precedência crescente).

• .env
• .env.production, .env.development, .env.test (dependendo do valor de NODE_ENV)
• .env.local

FOO=hello
BAR=world

Variáveis também podem ser definidas via linha de comando.

FOO=helloworld bun run dev

# Usando CMD
set FOO=helloworld && bun run dev

# Usando PowerShell
$env:FOO="helloworld"; bun run dev

Solução multiplataforma com Windows

Para uma solução multiplataforma, você pode usar bun shell. Por exemplo, o comando bun exec.

bun exec 'FOO=helloworld bun run dev'

No Windows, scripts package.json chamados com bun run usarão automaticamente o bun shell, tornando o seguinte também multiplataforma.

"scripts": {
  "dev": "NODE_ENV=development bun --watch app.ts",
},

Ou programaticamente atribuindo uma propriedade a process.env.

process.env.FOO = "hello";

---

Especificando manualmente arquivos .env

O Bun suporta --env-file para substituir qual arquivo .env específico carregar. Você pode usar --env-file ao executar scripts no runtime do bun ou ao executar scripts package.json.

bun --env-file=.env.1 src/index.ts

bun --env-file=.env.abc --env-file=.env.def run build

Desabilitando carregamento automático de .env

Use --no-env-file para desabilitar o carregamento automático de arquivos .env do Bun. Isso é útil em ambientes de produção ou pipelines CI/CD onde você quer confiar apenas em variáveis de ambiente do sistema.

bun run --no-env-file index.ts

Isso também pode ser configurado no bunfig.toml:

# Desabilita carregamento de arquivos .env
env = false

Arquivos de ambiente fornecidos explicitamente via --env-file ainda serão carregados mesmo quando o carregamento padrão estiver desabilitado.

---

Aspas

O Bun suporta aspas duplas, aspas simples e crases de template literal:

FOO='hello'
FOO="hello"
FOO=`hello`

Expansão

Variáveis de ambiente são automaticamente expandidas. Isso significa que você pode referenciar variáveis definidas anteriormente em suas variáveis de ambiente.

FOO=world
BAR=hello$FOO

process.env.BAR; // => "helloworld"

Isso é útil para construir strings de conexão ou outros valores compostos.

DB_USER=postgres
DB_PASSWORD=secret
DB_HOST=localhost
DB_PORT=5432
DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME

Isso pode ser desabilitado escapando o $ com uma backslash.

FOO=world
BAR=hello\$FOO

process.env.BAR; // => "hello$FOO"

dotenv

De modo geral, você não precisará mais de dotenv ou dotenv-expand, porque o Bun lê arquivos .env automaticamente.

Lendo variáveis de ambiente

As variáveis de ambiente atuais podem ser acessadas via process.env.

process.env.API_TOKEN; // => "secret"

O Bun também expõe estas variáveis via Bun.env e import.meta.env, que é um alias simples de process.env.

Bun.env.API_TOKEN; // => "secret"
import.meta.env.API_TOKEN; // => "secret"

Para imprimir todas as variáveis de ambiente atualmente definidas na linha de comando, execute bun --print process.env. Isso é útil para depuração.

bun --print process.env
BAZ=stuff
FOOBAR=aaaaaa
<lots more lines>

TypeScript

No TypeScript, todas as propriedades de process.env são tipadas como string | undefined.

Bun.env.whatever;
// string | undefined

Para obter autocompletar e dizer ao TypeScript para tratar uma variável como uma string não opcional, usaremos interface merging.

declare module "bun" {
  interface Env {
    AWESOME: string;
  }
}

Adicione esta linha a qualquer arquivo no seu projeto. Isso adicionará globalmente a propriedade AWESOME a process.env e Bun.env.

process.env.AWESOME; // => string

Configurando o Bun

Estas variáveis de ambiente são lidas pelo Bun e configuram aspectos do seu comportamento.

Nome	Descrição
NODE_TLS_REJECT_UNAUTHORIZED	NODE_TLS_REJECT_UNAUTHORIZED=0 desabilita validação de certificado SSL. Isso é útil para testes e depuração, mas você deve ter muita hesitação em usar isso em produção. Nota: Esta variável de ambiente foi originalmente introduzida pelo Node.js e mantivemos o nome para compatibilidade.
BUN_CONFIG_VERBOSE_FETCH	Se BUN_CONFIG_VERBOSE_FETCH=curl, então requisições fetch registrarão a url, método, cabeçalhos de requisição e cabeçalhos de resposta no console. Isso é útil para depurar requisições de rede. Isso também funciona com node:http. BUN_CONFIG_VERBOSE_FETCH=1 é equivalente a BUN_CONFIG_VERBOSE_FETCH=curl exceto sem a saída curl.
BUN_RUNTIME_TRANSPILER_CACHE_PATH	O runtime transpiler armazena em cache a saída transpilada de arquivos fonte maiores que 50 kb. Isso faz com que CLIs usando Bun carreguem mais rápido. Se BUN_RUNTIME_TRANSPILER_CACHE_PATH estiver definido, então o runtime transpiler armazenará em cache a saída transpilada no diretório especificado. Se BUN_RUNTIME_TRANSPILER_CACHE_PATH estiver definido como uma string vazia ou a string "0", então o runtime transpiler não armazenará em cache a saída transpilada. Se BUN_RUNTIME_TRANSPILER_CACHE_PATH não estiver definido, então o runtime transpiler armazenará em cache a saída transpilada no diretório de cache específico da plataforma.
TMPDIR	O Bun ocasionalmente requer um diretório para armazenar assets intermediários durante bundling ou outras operações. Se não definido, usa o diretório temporário específico da plataforma: /tmp no Linux, /private/tmp no macOS.
NO_COLOR	Se NO_COLOR=1, então a saída de cor ANSI está desabilitada.
FORCE_COLOR	Se FORCE_COLOR=1, então a saída de cor ANSI é forçada a habilitar, mesmo se NO_COLOR estiver definido.
BUN_CONFIG_MAX_HTTP_REQUESTS	Controla o número máximo de requisições HTTP concorrentes enviadas por fetch e bun install. Padrão 256. Se você estiver enfrentando limites de taxa ou problemas de conexão, pode reduzir este número.
BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD	Se BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD=true, então bun --watch não limpará o console ao recarregar
DO_NOT_TRACK	Desabilita upload de relatórios de crash para bun.report em crash. No macOS e Windows, uploads de relatórios de crash estão habilitados por padrão. Caso contrário, telemetria não é enviada ainda em 21 de maio de 2024, mas planejamos adicionar telemetria nas próximas semanas. Se DO_NOT_TRACK=1, então upload automático de relatórios de crash e telemetria estão ambos desabilitados.
BUN_OPTIONS	Prepende argumentos de linha de comando a qualquer execução do Bun. Por exemplo, BUN_OPTIONS="--hot" faz bun run dev se comportar como bun --hot run dev

Cache do runtime transpiler

Para arquivos maiores que 50 KB, o Bun armazena em cache a saída transpilada em $BUN_RUNTIME_TRANSPILER_CACHE_PATH ou no diretório de cache específico da plataforma. Isso faz com que CLIs usando Bun carreguem mais rápido.

Este cache de transpiler é global e compartilhado entre todos os projetos. É seguro deletar o cache a qualquer momento. É um cache endereçável por conteúdo, então nunca conterá entradas duplicadas. Também é seguro deletar o cache enquanto um processo Bun está em execução.

É recomendado desabilitar este cache ao usar sistemas de arquivos efêmeros como Docker. Imagens Docker do Bun automaticamente desabilitam este cache.

Desabilitar o cache do runtime transpiler

Para desabilitar o cache do runtime transpiler, defina BUN_RUNTIME_TRANSPILER_CACHE_PATH como uma string vazia ou a string "0".

BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev

O que ele armazena em cache?

Ele armazena em cache:

• A saída transpilada de arquivos fonte maiores que 50 KB.
• O sourcemap para a saída transpilada do arquivo

A extensão de arquivo .pile é usada para estes arquivos em cache.