import Run from "/snippets/cli/run.mdx";

O Bun Runtime foi projetado para iniciar rapidamente e executar com velocidade.

Internamente, o Bun usa o motor JavaScriptCore, que é desenvolvido pela Apple para o Safari. Na maioria dos casos, o desempenho de inicialização e execução é mais rápido que o V8, o motor usado pelo Node.js e navegadores baseados no Chromium. Seu transpilador e runtime são escritos em Zig, uma linguagem moderna e de alto desempenho. No Linux, isso se traduz em tempos de inicialização 4 vezes mais rápidos que o Node.js.

Comando	Tempo
bun hello.js	5.2ms
node hello.js	25.1ms

Este benchmark é baseado na execução de um script Hello World simples no Linux

Executar um arquivo

Use bun run para executar um arquivo fonte.

bun run index.js

O Bun suporta TypeScript e JSX nativamente. Cada arquivo é transpilado em tempo de execução pelo transpilador nativo rápido do Bun antes de ser executado.

bun run index.js
bun run index.jsx
bun run index.ts
bun run index.tsx

Alternativamente, você pode omitir a palavra-chave run e usar o comando "nu"; ele se comporta de forma idêntica.

bun index.tsx
bun index.js

--watch

Para executar um arquivo no modo watch, use a flag --watch.

bun --watch run index.tsx

::: note Ao usar bun run, coloque as flags do Bun como --watch imediatamente após bun. :::

bun --watch run dev # ✔️ faça isso
bun run dev --watch # ❌ não faça isso

Flags que ocorrem no final do comando serão ignoradas e passadas para o próprio script "dev".

Executar um script package.json

::: note Compare com npm run <script> ou yarn <script> :::

bun [flags do bun] run <script> [flags do script]

Seu package.json pode definir vários "scripts" nomeados que correspondem a comandos do shell.

{
  // ... outros campos
  "scripts": {
    "clean": "rm -rf dist && echo 'Concluído.'",
    "dev": "bun server.ts"
  }
}

Use bun run <script> para executar estes scripts.

bun run clean
rm -rf dist && echo 'Concluído.'

Limpando...
Concluído.

O Bun executa o comando do script em um subshell. No Linux e macOS, ele verifica os seguintes shells em ordem, usando o primeiro que encontrar: bash, sh, zsh. No Windows, ele usa bun shell para suportar sintaxe estilo bash e muitos comandos comuns.

NOTE

⚡️ O tempo de inicialização para `npm run` no Linux é de aproximadamente 170ms; com o Bun é `6ms`.

Scripts também podem ser executados com o comando mais curto bun <script>, no entanto, se houver um comando builtin do bun com o mesmo nome, o comando builtin tem precedência. Neste caso, use o comando mais explícito bun run <script> para executar seu script do package.

bun run dev

Para ver uma lista de scripts disponíveis, execute bun run sem nenhum argumento.

bun run

scripts quickstart:

 bun run clean
   rm -rf dist && echo 'Concluído.'

 bun run dev
   bun server.ts

2 scripts

O Bun respeita hooks de lifecycle. Por exemplo, bun run clean executará preclean e postclean, se definidos. Se o pre<script> falhar, o Bun não executará o próprio script.

--bun

É comum que scripts package.json façam referência a CLIs instalados localmente como vite ou next. Esses CLIs são frequentemente arquivos JavaScript marcados com um shebang para indicar que devem ser executados com node.

#!/usr/bin/env node

// faz algo

Por padrão, o Bun respeita este shebang e executa o script com node. No entanto, você pode substituir este comportamento com a flag --bun. Para CLIs baseados em Node.js, isso executará o CLI com o Bun em vez do Node.js.

bun run --bun vite

Filtragem

Em monorepos contendo múltiplos pacotes, você pode usar o argumento --filter para executar scripts em muitos pacotes de uma vez.

Use bun run --filter <nome_padrao> <script> para executar <script> em todos os pacotes cujo nome corresponda a <nome_padrao>. Por exemplo, se você tiver subdiretórios contendo pacotes nomeados foo, bar e baz, executar

bun run --filter 'ba*' <script>

executará <script> tanto em bar quanto em baz, mas não em foo.

Encontre mais detalhes na página de documentação para filter.

bun run - para canalizar código do stdin

bun run - permite ler JavaScript, TypeScript, TSX ou JSX do stdin e executá-lo sem escrever em um arquivo temporário primeiro.

echo "console.log('Olá')" | bun run -

Olá

Você também pode usar bun run - para redirecionar arquivos para o Bun. Por exemplo, para executar um arquivo .js como se fosse um arquivo .ts:

echo "console.log!('Isto é TypeScript!' as any)" > secretly-typescript.js
bun run - < secretly-typescript.js

Isto é TypeScript!

Por conveniência, todo o código é tratado como TypeScript com suporte a JSX ao usar bun run -.

bun run --console-depth

Controle a profundidade da inspeção de objetos na saída do console com a flag --console-depth.

bun --console-depth 5 run index.tsx

Isso define quão profundamente os objetos aninhados são exibidos na saída do console.log(). A profundidade padrão é 2. Valores mais altos mostram mais propriedades aninhadas, mas podem produzir saída verbosa para objetos complexos.

const nested = { a: { b: { c: { d: "profundo" } } } };
console.log(nested);
// Com --console-depth 2 (padrão): { a: { b: [Object] } }
// Com --console-depth 4: { a: { b: { c: { d: 'profundo' } } } }

bun run --smol

Em ambientes com restrição de memória, use a flag --smol para reduzir o uso de memória com custo para o desempenho.

bun --smol run index.tsx

Isso faz com que o garbage collector seja executado com mais frequência, o que pode desacelerar a execução. No entanto, pode ser útil em ambientes com memória limitada. O Bun ajusta automaticamente o tamanho do heap do garbage collector com base na memória disponível (considerando cgroups e outros limites de memória) com e sem a flag --smol, então isso é principalmente útil para casos onde você deseja que o tamanho do heap cresça mais lentamente.

Ordem de resolução

Caminhos absolutos e caminhos começando com ./ ou .\\ são sempre executados como arquivos fonte. A menos que esteja usando bun run, executar um arquivo com uma extensão permitida preferirá o arquivo sobre um script package.json.

Quando há um script package.json e um arquivo com o mesmo nome, bun run prioriza o script package.json. A ordem completa de resolução é:

1. Scripts package.json, ex: bun run build
2. Arquivos fonte, ex: bun run src/main.js
3. Binários de pacotes do projeto, ex: bun add eslint && bun run eslint
4. (apenas bun run) Comandos do sistema, ex: bun run ls