Configurando uma Aplicação TypeScript com Bun

Se você tem gerenciado projetos TypeScript com Node.js, conhece o atrito: instalar ts-node ou tsx, configurar uma etapa de build, conectar seus scripts e só então começar a escrever código. Bun remove a maior parte dessa sobrecarga. É um runtime JavaScript moderno que executa arquivos TypeScript diretamente, vem com um gerenciador de pacotes integrado e atua como executor de tarefas—tudo em uma única ferramenta. Este guia orienta você através de uma configuração completa de projeto TypeScript com Bun para que você possa ir do zero à execução de TypeScript em minutos.

O Que É Bun e Por Que Usá-lo para TypeScript?

Bun é um runtime JavaScript rápido construído sobre JavaScriptCore e escrito em Zig. O que o torna especial para desenvolvimento TypeScript é que ele transpila nativamente arquivos .ts e .tsx em tempo de execução—sem necessidade de etapa de build separada. Ao contrário da combinação Node.js + ts-node, o Bun lida com a transpilação internamente, o que significa tempos de inicialização visivelmente mais rápidos e um fluxo de trabalho de desenvolvimento mais simples.

Além do runtime, o Bun substitui várias ferramentas de uma vez:

• Runtime – executa TypeScript e JavaScript diretamente
• Gerenciador de pacotes – alternativa mais rápida ao npm, yarn ou pnpm
• Executor de tarefas – executa scripts definidos no package.json

Criando um Novo Projeto TypeScript com Bun

Comece instalando o Bun, depois crie um novo projeto:

bun init

O Bun solicitará um ponto de entrada. Use src/index.ts para manter as coisas organizadas:

entry point (index.ts): src/index.ts

Isso gera uma estrutura de projeto mínima:

my-app/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── bun.lock

O arquivo bun.lock é o arquivo de lock de dependências do Bun usado pelo gerenciador de pacotes do Bun para garantir instalações consistentes.

Instalando Definições de Tipo do Bun

Se @types/bun ainda não estiver presente no seu projeto, instale-o como dependência de desenvolvimento para obter IntelliSense adequado e verificação de tipos para APIs específicas do Bun:

bun add -d @types/bun

Isso fornece acesso tipado às APIs integradas do Bun como Bun.serve(), Bun.file() e bun:sqlite. Consulte a documentação oficial de TypeScript do Bun para mais detalhes.

tsconfig.json Recomendado para Projetos Bun

O Bun funciona sem um tsconfig.json, mas você vai querer um para suporte de IDE e verificação de tipos. A configuração chave para a configuração TypeScript do Bun é "moduleResolution": "bundler", que se alinha com a forma como o Bun resolve módulos internamente.

Outras opções importantes a incluir:

• "target": "ESNext" e "lib": ["ESNext"] — use recursos JavaScript modernos
• "strict": true — capture erros cedo
• "noEmit": true — Bun lida com a execução, então você não precisa de saída compilada
• "verbatimModuleSyntax": true — garante importações limpas de apenas tipos
• "allowImportingTsExtensions": true — permite importar arquivos .ts com suas extensões

Aqui está um exemplo completo:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ESNext"],
    "strict": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

⚠️ Importante: O transpilador do Bun remove anotações de tipo para velocidade—ele não realiza verificação completa de tipos em tempo de execução. Execute bunx tsc --noEmit separadamente durante o desenvolvimento ou no CI para capturar erros de tipo.

Executando Arquivos TypeScript e Gerenciando Scripts

Executar um arquivo TypeScript com Bun é simples:

bun run src/index.ts

Para desenvolvimento com reinicializações automáticas em alterações de arquivo, use o modo watch:

bun --watch src/index.ts

Adicione seus fluxos de trabalho comuns aos scripts do package.json:

{
  "scripts": {
    "dev": "bun --watch src/index.ts",
    "start": "bun run src/index.ts",
    "typecheck": "bunx tsc --noEmit"
  }
}

O Bun executa esses scripts diretamente—nenhum executor de tarefas extra necessário.

O Que Mais o Bun Oferece

Uma vez que sua configuração de projeto TypeScript com Bun esteja no lugar, você tem acesso a várias capacidades integradas sem adicionar dependências:

• Executor de testes — bun test suporta uma API compatível com Jest pronta para uso
• Bundler — bun build lida com empacotamento de assets frontend
• SQLite — bun:sqlite fornece uma interface de banco de dados nativa e tipada

Esses recursos não são necessários para uma configuração básica, mas estão disponíveis no momento em que você precisar deles. Você pode explorar o conjunto completo de recursos na documentação oficial do Bun.

Conclusão

A principal mudança ao usar TypeScript com Bun é aceitar que o runtime lida com a transpilação enquanto o tsc lida com a segurança de tipos—são preocupações separadas. Uma vez que isso fique claro, o fluxo de trabalho é limpo: inicialize um projeto, instale @types/bun se necessário, configure seu tsconfig.json com resolução de módulos estilo bundler e execute seus arquivos TypeScript diretamente. Sem pipeline de build para manter, sem ferramentas extras para instalar.

Perguntas Frequentes

O Bun realiza verificação de tipos TypeScript ao executar arquivos?

Não. O Bun remove anotações de tipo durante a transpilação para velocidade, mas não executa o verificador de tipos do TypeScript. Você precisa executar tsc com a flag noEmit separadamente, seja durante o desenvolvimento ou como parte do seu pipeline de CI, para capturar erros de tipo antes que cheguem à produção.

Posso usar pacotes npm existentes em um projeto TypeScript com Bun?

Sim. O gerenciador de pacotes do Bun é totalmente compatível com o registro npm. Você instala pacotes com bun add assim como faria com npm install. A maioria dos pacotes que funcionam com Node.js funcionam com Bun, embora pacotes que dependem de addons nativos específicos do Node possam ter limitações de compatibilidade.

O Bun é estável o suficiente para aplicações TypeScript em produção?

O Bun alcançou a versão 1.0 em setembro de 2023 e tem continuado com lançamentos estáveis regulares desde então. Muitas equipes o usam em produção, mas você deve testar suas dependências e cargas de trabalho específicas. A compatibilidade com a API do Node.js é ampla, mas ainda não está completa, então verifique quaisquer APIs específicas do Node das quais seu projeto depende.

Como o desempenho do Bun se compara ao Node.js para projetos TypeScript?

O Bun geralmente inicia mais rápido que o Node.js com ts-node ou tsx porque transpila TypeScript nativamente sem uma etapa de compilação separada. A instalação de pacotes também é significativamente mais rápida devido ao seu resolvedor otimizado e sistema de instalação. O desempenho real em tempo de execução varia por carga de trabalho, mas as melhorias no tempo de inicialização são consistentemente perceptíveis.