unbuild para TypeScript: guia completo com exemplos práticos

No ecossistema moderno de JavaScript e TypeScript, a compilação de projetos é uma das tarefas essenciais. Desenvolvedores frequentemente enfrentam a necessidade de configurar ambientes complexos para Webpack, Rollup ou esbuild. A biblioteca unbuild oferece uma solução elegante — um sistema de build unificado que combina as melhores práticas e ferramentas em uma única interface. Não se trata apenas de mais um bundler, mas sim de um wrapper unificado sobre esbuild e Rollup, que determina automaticamente a estratégia de build ideal para o seu projeto.

O principal objetivo do unbuild é simplificar ao máximo o processo de build de bibliotecas TypeScript. Em vez de gastar horas configurando arquivos de configuração, o desenvolvedor recebe uma solução pronta para uso "out of the box". A biblioteca gera automaticamente builds CommonJS e ESM, cria declarações de tipos (d.ts), otimiza os bundles e suporta os recursos modernos do TypeScript. Isso torna o unbuild a escolha ideal para autores de pacotes npm e projetos open-source.

O Unbuild é especialmente útil nos seguintes cenários: criação de monorepositórios, build de bibliotecas com suporte a tree-shaking, publicação de pacotes com código-fonte TypeScript e migração de bundlers legados. Graças ao suporte nativo para exportações no package.json e à detecção automática de pontos de entrada, a biblioteca permite que você foque em escrever código, e não em configurar infraestrutura.

Instalação

Para instalar o unbuild, utilize o gerenciador de pacotes npm (ou alternativas como yarn, pnpm). A biblioteca é instalada como uma dependência de desenvolvimento:

npm install -D unbuild

Ou com yarn:

yarn add -D unbuild

Para pnpm:

pnpm add -D unbuild

Após a instalação, é recomendado adicionar um script de build no package.json:

{
  "scripts": {
    "build": "unbuild",
    "dev": "unbuild --watch"
  }
}

Início Rápido

Vamos criar um projeto mínimo funcional. Estrutura de arquivos:

my-library/
├── src/
│   └── index.ts
├── package.json
└── tsconfig.json

Conteúdo do src/index.ts:

export function greet(name: string): string {
  return `Olá, ${name}!`;
}

export const version = '1.0.0';

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

Agora, execute o build:

npx unbuild

Após a execução, os seguintes arquivos serão gerados na pasta dist:

dist/index.mjs — build ESM
dist/index.cjs — build CommonJS
dist/index.d.ts — declarações de tipos
dist/index.d.mts — declarações para ESM

O Unbuild cria automaticamente ambos os builds e gera as declarações TypeScript. Para configurar as exportações no package.json, adicione:

{
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}