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

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.